Calculating Shipping and Tax

Overview

In order for shipping or tax to be applied to your orders, you must first turn either of these features on inside of your Merchant Portal. When you do so, you will also be prompted to provide Skipify with a Callback URL. We will make a call to this URL whenever an address is selected by a customer during checkout and read the response body for tax and/or shipping information.

This will allow Skipify to properly display the correct shipping and tax details based on your customer's address. When they make a selection, we will update the order with the new totals before submitting payment to your gateway.

Callback Request

To retrieve shipping & tax information, Skipify's servers will send a request your specified URL:

POST {{callbackUrl}}

Request Body Parameters This request will include the following parameters:
Request ParameterTypeDescription
merchantOrderIdstringThis is your unique identifier for the order
SkipifyOrderIDstring (uuid)This is Skipify's unique Identifier for the order

Ex: 77a051d8-be26-11eb-8529-0242ac130003
shippingAddressobjectThis is the address that was selected by the customer. For details of this object, see below

The shippingAddress Object

ParameterTypeDescription
shippingAddressIdstring (uuid)Skipify's unique identifier for the address that was chosen by the customer during checkout.

We require that you send this identifier back in the response so that we can accurately validate and correlate the address internally
streetAddressstringStreet address

Ex: 123 Main Street
addressLocalitystringCity of the address

Ex: Denver
addressRegionstringState abbreviation of the address

Ex: CO
postalCodestringZip code of the address

Ex: 80209
Request Body Example
{
  "merchantOrderId": "someMerchantOrderId",
  "goCartOrderId": "77a051d8-be26-11eb-8529-0242ac130003",
  "shippingAddress": {
    "shippingAddressId": "53e2a852-be23-11eb-8529-0242ac130003",
    "streetAddress": "123 Main Street",
    "addressLocality": "Denver",
    "addressRegion": "CO",
    "postalCode": "80209"
  }
}

Callback Response

Response Body Parameters
ParameterTypeDescription
shippingAddressIdstring (uuid)This is the ID that was provided when Skipify made the request to you. We use this to validate and correlate the data internally
currencyCodestringThe ISO 4217 three-character currency code. Today, Skipify only accepts USD.
shippingOptionsobject, nullableThis is a list of options for shipping - see schema below
preferred ShippingOptionIdinteger, nullableThe preferred pre-selected shipping option ("id") from the shippingOptions list. If provided, this will be pre-selected and display during checkout.
taxnumber (double), nullableTax assessed based on the address of the order. However, if you've opted out of Tax, this value can be null.

Min value is 0.

The Shipping Options Object

Skipify allows for up to 10 shipping options to be passed through. See below for details:

ParameterTypeDescription
descriptionstringDetails of a shipping option
idintegerA unique numeric identifier. This is used to identify the default shipping option (preferredShippingOptionId) in the above response.

Min value: 1
Max Value: 10
namestringA unique name that represents this shipping option. This will be displayed to the customer.

Ex: Ground Freight
pricenumber (double)Cost for the shipping option in question (in USD)

Ex: 25.98
Response Body Example This is an example of the response we would expect from you when we send you the request:
{
  "shippingAddressId": "53e2a852-be23-11eb-8529-0242ac130003",
  "currencyCode": "USD",
  "shippingOptions": [
    {
      "id": 1,
      "name": "Ground Freight",
      "price": 25.98
    },
    {
      "id": 2,
      "name": "Next Day Air",
      "price": 42.50
    }
  ],
  "preferredShippingOptionId": 1,
  "tax": 10.5
}