====== Custom Shipping Code XPS Integration ======

The following page details integrating [[https://xpsship.com|XPS]] into your Foxy store for fetching shipping rates from any of their supported providers, using the [[v:2.0:shipping:custom_code|Custom Shipping Code functionality]] available for Foxy stores.

===== Requirements =====

  * A Foxy store on version 2.0
  * At least one category configured with a delivery type of "Shipped using live shipping rates"
  * An active [[https://xpsship.com|XPS]]


===== Installation =====

Below is the custom shipping code you'll use to connect to XPS, and below that is the steps to install it on your store.

<code javascript>
// Set to the API key of your XPS account
let api_key = 'XPS-API-KEY';
let customer_id = 'XPS-CUSTOMER-ID';
// Weight units for the store ('lb' or 'kg')
let weight_unit = 'lb';
// Length units for the store ('in' or 'cm')
let length_unit = 'in';
 
 
 
const shipment = cart['_embedded']['fx:shipment'];
 
let payload = {
    "carrierCode": "",
    "serviceCode": "",
    "packageTypeCode": "",
    "sender": {
        "country": shipment['origin_country'],
        "zip": shipment['origin_postal_code']
    },
    "receiver": {
        "city": shipment['city'],
        "country": shipment['country'],
        "zip": shipment['postal_code'],
    },
    "residential": shipment['is_residential'] ? true : false,
    "signatureOptionCode": null,
    "contentDescription": "",
    "weightUnit": weight_unit,
    "dimUnit": length_unit,
    "currency": cart.currency_code,
    "customsCurrency": cart.currency_code,
    "pieces": [
        // Populated below
    ],
    "billing": {
        "party": "sender"
    }
};
 
// Pieces array: If you need to calculate for multiple packages, modify this array to dynamically build out your different packages as needed 
let package_details = {
    "weight": shipment['total_weight'].toString(),
    "length": null,
    "width": null,
    "height": null,
    "insuranceAmount": null,
    "declaredValue": null
    };
 
payload.pieces.push(package_details);
 
try {
    const endpoint = 'https://xpsshipper.com/restapi/v1/customers/' + customer_id + '/quote';
    const response = await fetch(endpoint, {
        method: 'POST', 
        body: JSON.stringify(payload),
        headers: {
            "Authorization": "RSIS " + api_key,
            "Content-Type": "application/json"
        }
    });
    const data = await response.json();

    if (response.status != 200) {
        console.log(data.errorCategory + ": " + data.error);
    } else {
        for (let r = 0; r < data.quotes.length; r++) {
            const rate = data.quotes[r];
    
            rates.add(10000 + r, rate.totalAmount, '', rate.serviceDescription);
        }
    }
} catch(err) {
  console.log(err);
}
</code>

==== Steps ====

  - Log in to your store's Foxy administration
  - Head to the "Shipping" page
  - Scroll down until you see the "Custom Shipping Code" option, and check the option for "use custom code".
  - In the code editor that appears, copy and paste the code shown above. Don't save it just yet.
  - In a new tab, log in to your XPS account
  - In the XPS settings, go to the go to the [[https://xpsshipper.com/ec/#/settings/apiKey|API Key / Customer ID]] section
  - Copy the API key and Customer ID to your clipboard, and in the code you pasted into your Foxy admin above, replace ''XPS-API-KEY'' with your API Key and ''XPS-CUSTOMER-ID'' with your Customer ID.
  - Configure the remainder of the configuration options for weight/length units as needed.
  - Click the "Update" button to save your new settings
  - Wait ~10-15 seconds and refresh the page (the custom shipping code feature is a separate system, so takes a moment to initialize, you should see your custom code again after refreshing if it was successful)
  - You're done! Now you can test it out!

To test out the new rates after saving, you can simply add a product to your cart that belongs to a live rate shippable category. On the cart or checkout, after entering a shipping address, you should see your rates returning from your XPS account.


===== Taking It Further =====
This integration is fairly basic - it just returns all rates from XPS, and passes it some default values. You can review [[https://xpsshipper.com/restapi/docs/v1-ecommerce/endpoints/quote/|the XPS documentation on quote requests]] with their API here to customise the integration above further as needed.

You can also customise the rates returned, to only output specific rates or work with them further using [[v:2.0:shipping:custom_code:api|our custom shipping code API documented here]].