Introduction

The Checkout API offers enhanced flexibility and allows merchant accounts to programmatically quote customer orders (including shipping, duties, taxes and other applicable charges), and implement fully-customized checkout and payment features on more than 100 currencies.

Our API is organized around REST and uses standard HTTP built-in features such as HTTP authentication, HTTP error codes and HTTP verbs, which are understood by off-the-shelf HTTP clients. All API responses, including errors, are based on JSON.

Authentication

We support HTTP Basic Authentication with an API Client ID and an API Secret, as well as the OAuth2 Client Credential grant. API clients are free to use any of these two Authentication methods.

HTTP Basic Authentication

Authenticating with HTTP Basic Authentication

# Every request should include the Authorization and Partner Key headers
curl "https://checkout.crossborder.fedex.com/v2/checkout" \
  -H "Authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0" \
  -H "X-FCB-Partner-Key: MyPartnerKey"

Note: The Authorization header is obtained by base64-encoding the string "APIClientID:APIClientSecret"

<?php

$credentials = new \FedExCrossBorder\Auth\Credentials('APIClientID', 'APIClientSecret', 'MyPartnerKey');

$checkoutClient = new \FedExCrossBorder\Checkout\CheckoutClient();
$checkoutClient->setCredentials($credentials);

// $cart is a \FedExCrossBorder\Checkout\Entity\Cart object
$checkout = $checkoutClient->createCheckout($cart);

In order to use HTTP Basic Authentication, API clients must use the standard HTTP Authorization header, using their API Client ID as username and their API Secret as password.

Additionally, API clients must send a custom Partner Key header, which identifies the Partner account and is also verified against the API Client ID.

With this Authentication method, all API requests should include these two headers.

Checkout Base URL: https://checkout.crossborder.fedex.com/v2/checkout

OAuth2 Client Credentials

Oauth2 Client Credentials Request

curl -X POST \
  https://secure.crossborder.fedex.com/oauth \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials

<?php

$credentials = new \FedExCrossBorder\Auth\Credentials('APIClientID', 'APIClientSecret', 'MyPartnerKey');

$oauthClient = new \FedExCrossBorder\Auth\OauthClient();
$oauthClient->setCredentials($credentials);

// $tokenResponse is a \FedExCrossBorder\Auth\AccessToken object
$tokenResponse = $oauthClient->clientCredentials();

Oauth2 Client Credentials Response

{
  "access_token": "00f0af1bb0a7098e04cfe5ae461046f952a7e587",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": null
}

We support the OAuth2 Client Credentials grant. With this Authentication method, API clients must first request a Bearer Authentication token by calling our OAuth2 endpoint as follows:

HTTP Request

POST https://secure.crossborder.fedex.com/oauth

Request Parameters

Parameter	Type	Description
grant_type	string	The value should be client_credentials, which is the supported Oauth2 Grant Type.

Response Object

Attribute	Type	Description
access_token	string	The Oauth2 Bearer token.
expires_in	integer	The expiration time in seconds.
token_type	string	The token type, which will be always Bearer.
scope	string	The Oauth2 Scope for which the token is given permissions to.

Using the Bearer Token

Using the Bearer Token

# Every request should include the Authorization and Partner Key headers
curl "https://checkout.crossborder.fedex.com/v2/checkout" \
  -H "Authorization: Bearer 00f0af1bb0a7098e04cfe5ae461046f952a7e587" \
  -H "X-FCB-Partner-Key: MyPartnerKey"

Note: Once a Bearer token expires, a new token needs to requested

<?php

// $tokenResponse is a \FedExCrossBorder\Auth\AccessToken object
$checkoutClient = new \FedExCrossBorder\Checkout\CheckoutClient();
$checkoutClient->setAccessToken($tokenResponse->getAccessToken());
$checkoutClient->setPartnerKey('MyPartnerKey');

// $cart is a \FedExCrossBorder\Checkout\Entity\Cart object
$checkout = $checkoutClient->createCheckout($cart);

Once a Bearer Token has been issued, subsequent API calls must be directed to the Checkout Base URL along with the Bearer Token as part of the Authorization header.

Checkout Base URL: https://checkout.crossborder.fedex.com/v2/checkout

Checkout API

Create Checkout

Create Checkout Request

curl -X POST \
  https://checkout.crossborder.fedex.com/v2/checkout \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: MyPartnerKey' \
  -d '{
      "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "My Biz",
        "address_1": "10-123 1/2 MAIN STREET NW",
        "address_2": "MONTREAL QC H3Z 2Y7",
        "city": "Montreal",
        "country": "CA",
        "state": "Quebec",
        "zip": "H3Z 2Y7",
        "phone": "1-514-888-9999",
        "email": "[email protected]",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3",
        "tax_id": "123456789"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "My Biz",
        "address_1": "10-123 1/2 MAIN STREET NW",
        "address_2": "MONTREAL QC H3Z 2Y7",
        "city": "Montreal",
        "country": "CA",
        "state": "Quebec",
        "zip": "H3Z 2Y7",
        "phone": "1-514-888-9999",
        "email": "[email protected]",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3",
        "tax_id": "123456789"
      },
      "domestic_shipping_charge": "0.00",
      "shipping_method": {
        "code": 1
      },
      "merchant_currency": "USD",
      "charge_loss_damage_protection": true,
      "charge_duty_tax": true,
      "products": [
        {
          "id": "1766738",
          "name": "576 #2 Pencils",
          "quantity": 1,
          "price": "37.25",
          "shipping": "0.00",
          "country_of_origin": "US",
          "distribution_country": "US",
          "distribution_zip": "",
          "product_transit": 3,
          "custom_1": "",
          "custom_2": "",
          "custom_3": ""
        }
      ],
      "order_transit": 3,
      "retailer_order_number": "A-1234-001",
      "custom_order_1": "Custom Value 1",
      "custom_order_2": "Custom Value 2",
      "custom_order_3": "Custom Value 3",
      "merchant_shipping_methods": null,
      "customer_attributes": {
        "locale": "en_US",
        "timezone": "America/Montreal",
        "ip": "8.8.8.8"
      },
      "merchant_attributes": {
        "confirmation_uri": null,
        "merchant_direct": false
      }
    }'

<?php
$cart = new Cart();

// Setting some Shipping Address
$cart->setShippingAddress(
    new Address([
        'first_name' => 'John',
        'last_name' => 'Doe',
        'company' => 'My Biz',
        'address_1' => '10-123 1/2 MAIN STREET NW',
        'address_2' => 'MONTREAL QC H3Z 2Y7',
        'city' => 'Montreal',
        'country' => 'CA',
        'state' => 'Quebec',
        'zip' => 'H3Z 2Y7',
        'phone' => '1-514-888-9999',
        'email' => '[email protected]',
        'custom_1' => 'Custom Value 1',
        'custom_2' => 'Custom Value 2',
        'custom_3' => 'Custom Value 3',
        'tax_id' => '123456789',
        ]
    )
);

// Billing and Shipping Address can be the same
$cart->setBillingAddress($cart->getShippingAddress());

// Set the Merchant currency to USD
$cart->setMerchantCurrency('USD');

// Adding a single product
$cart->addProduct(
    new Product([
        'id' => '1766738',
        'name' => '576 #2 Pencils',
        'quantity' => 1,
        'price' => '37.25',
        'shipping' => '0.00',
        'country_of_origin' => 'US',
        'distribution_country' => 'US',
        'distribution_zip' => '',
        'product_transit' => 3,
        'custom_1' => '',
        'custom_2' => '',
        'custom_3' => '',
        ]
    )
);

// International Standard Shipping Method
$cart->setShippingMethod(new ShippingMethodOption(ShippingMethodOption::INTERNATIONAL_STANDARD));

$checkout = $checkoutClient->createCheckout($cart);

The checkout process can be started with an empty or partially-filled shopping cart. The cart object contains multiple optional fields, such as the billing and shipping address, a product list, and additional order-level fields.

Create Checkout Response

{
  "checkout_id": "tzc5935e3a1361c6",
  "cart": {
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "My Biz",
      "address_1": "10-123 1/2 MAIN STREET NW",
      "address_2": "MONTREAL QC H3Z 2Y7",
      "city": "Montreal",
      "country": "CA",
      "state": "Quebec",
      "zip": "H3Z 2Y7",
      "phone": "1-514-888-9999",
      "email": "[email protected]",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3",
      "tax_id": "123456789"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "My Biz",
      "address_1": "10-123 1/2 MAIN STREET NW",
      "address_2": "MONTREAL QC H3Z 2Y7",
      "city": "Montreal",
      "country": "CA",
      "state": "Quebec",
      "zip": "H3Z 2Y7",
      "phone": "1-514-888-9999",
      "email": "[email protected]",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3",
      "tax_id": "123456789"
    },
    "domestic_shipping_charge": "0.00",
    "shipping_method": {
      "code": 1
    },
    "merchant_currency": "USD",
    "charge_loss_damage_protection": true,
    "charge_duty_tax": true,
    "products": [
      {
        "id": "1766738",
        "name": "576 #2 Pencils",
        "quantity": 1,
        "price": "37.25",
        "shipping": "0.00",
        "country_of_origin": "US",
        "distribution_country": "US",
        "distribution_zip": "",
        "product_transit": 3,
        "custom_1": "",
        "custom_2": "",
        "custom_3": ""
      }
    ],
    "order_transit": 3,
    "retailer_order_number": "A-1234-001",
    "custom_order_1": "Custom Value 1",
    "custom_order_2": "Custom Value 2",
    "custom_order_3": "Custom Value 3",
    "merchant_shipping_methods": null,
    "customer_attributes": {
      "locale": "en_US",
      "timezone": "America/Montreal",
      "ip": "8.8.8.8"
    },
    "merchant_attributes": {
      "confirmation_uri": null,
      "merchant_direct": false
    }
  },
  "available_shipping_methods": [
    {
      "code": 1,
      "name": "International Standard",
      "amount": "139.62",
      "delivery_date": "2017-07-24"
    }
  ],
  "available_payment_methods": [
    {
      "code": "VISA",
      "name": "Visa",
      "type": "creditcard"
    }
  ],
  "totals": {
    "currency": "CAD",
    "product_subtotals": [
      {
        "id": "1766738",
        "quantity": 1,
        "unit_price": "136.01",
        "total_price": "136.01"
      }
    ],
    "subtotal": "136.01",
    "charges": {
      "shipping": "139.62",
      "duty": "15.08",
      "tax": "47.95",
      "ddp": true,
      "intl_processing_fee": "0.00",
      "remote_area_surcharge": "0.00",
      "loss_damage_protection": "6.77"
    },
    "total": "345.43"
  },
  "merchantTotals": {
    "currency": "CAD",
    "product_subtotals": [
      {
        "id": "1766738",
        "quantity": 1,
        "unit_price": "136.01",
        "total_price": "136.01"
      }
    ],
    "subtotal": "136.01",
    "charges": {
      "shipping": "139.62",
      "duty": "15.08",
      "tax": "47.95",
      "ddp": true,
      "intl_processing_fee": "0.00",
      "remote_area_surcharge": "0.00",
      "loss_damage_protection": "6.77"
    },
    "total": "345.43"
  },
  "status": "Z",
  "order_id": null,
  "error": null,
  "extra": {
    "checkout_error_handling": true,
    "kount_uri_1": "https://checkout.crossborder.fedex.com/logo.htm?m=166800&s=tzc5935e3a1361c6",
    "kount_uri_2": "https://checkout.crossborder.fedex.com/logo.gif?m=166800&s=tzc5935e3a1361c6"
  }
}

HTTP Request

POST https://checkout.crossborder.fedex.com/v2/checkout

Request Parameters

Parameter	Type	Description
billing_address (required)	Address	An Address object indicating the billing address.
shipping_address (required)	Address	An Address object indicating the shipping address.
domestic_shipping_charge (optional)	string	Defines the cost of shipment on an order level from the vendor's location to a FedEx Cross Border Distribution Center.
shipping_method (optional)	ShippingMethodOption	A ShippingMethodOption object containing the selected shipping method.
merchant_currency (optional)	string	The currency the Merchant is settling in.
charge_loss_damage_protection (optional)	boolean	A boolean indicating whether or not the order will include Loss and Damage Protection.
charge_duty_tax	boolean	A boolean indicating whether or not the duties and taxes will be paid on checkout.
products	Product[]	An array of Product objects to be included in the order.
order_transit	integer	Defines the estimated domestic transit time (in Business Days) to the FedEx Cross Border Distribution Center.
retailer_order_number	string	A reference retailer or merchant order number.
custom_order_1	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_2	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_3	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
merchant_shipping_methods	MerchantShippingMethod[]	For Merchant Direct orders, an array of MerchantShippingMethod objects indicating the shipping methods available to the customer as defined by the merchant.
customer_attributes	CustomerAttributes	A CustomerAttributes object indicating the locale, timezone and IP address of the customer.
merchant_attributes	MerchantAttributes	A MerchantAttributes object indicating merchant-specific customizations.

Response Object

Attribute	Type	Description
checkout_id	string	The ID of the checkout process
cart	Cart	The current state of the Cart object
available_shipping_methods	AvailableShippingMethod[]	The list ot available shipping methods
available_payment_methods	AvailablePaymentMethod[]	The list of available payment methods
totals	CheckoutTotals	The checkout monetary totals expressed in the customer currency.
merchantTotals	CheckoutTotals	The checkout monetary totals expressed in the merchant currency.
status	string	The status of the checkout process
order_id	string	The Order ID, once an order has been placed.
error	CheckoutError	A detailed error object, if an error occurred, or null otherwise.
extra	CheckoutExtra	An associative array of additional information.

Create Checkout (Merchant Direct)

Create Checkout Request (Merchant Direct)

curl -X POST \
  https://checkout.crossborder.fedex.com/v2/checkout \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: MyPartnerKey' \
  -d '{
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "My Biz",
    "address_1": "10-123 1/2 MAIN STREET NW",
    "address_2": "MONTREAL QC H3Z 2Y7",
    "city": "Montreal",
    "country": "CA",
    "state": "Quebec",
    "zip": "H3Z 2Y7",
    "phone": "1-514-888-9999",
    "email": "[email protected]",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3",
    "tax_id": "123456789"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "My Biz",
    "address_1": "10-123 1/2 MAIN STREET NW",
    "address_2": "MONTREAL QC H3Z 2Y7",
    "city": "Montreal",
    "country": "CA",
    "state": "Quebec",
    "zip": "H3Z 2Y7",
    "phone": "1-514-888-9999",
    "email": "[email protected]",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3",
    "tax_id": "123456789"
  },
  "domestic_shipping_charge": "0.00",
  "shipping_method": {
    "code": 102
  },
  "merchant_currency": "USD",
  "charge_duty_tax": true,
  "charge_loss_damage_protection": true,
  "products": [
    {
      "id": "1766738",
      "name": "576 #2 Pencils",
      "quantity": 1,
      "price": "37.25",
      "shipping": "0.00",
      "country_of_origin": "US",
      "distribution_country": "US",
      "distribution_zip": "",
      "product_transit": 3,
      "custom_1": "",
      "custom_2": "",
      "custom_3": ""
    }
  ],
  "order_transit": 3,
  "retailer_order_number": "A-1234-001",
  "custom_order_1": "Custom Value 1",
  "custom_order_2": "Custom Value 2",
  "custom_order_3": "Custom Value 3",
  "customer_attributes": {
    "locale": "en_US",
    "timezone": "America/Montreal",
    "ip": "8.8.8.8"
  },
  "merchant_attributes": {
    "confirmation_uri": null,
    "merchant_direct": true
  },
  "merchant_shipping_methods": [
    {
      "code": 103,
      "name": "Merchant Super Express",
      "transit_time": 3,
      "dutiable_transit_cost": 200,
      "charged_transit_cost": 400,
      "charged_transit_cost_message": "10 Discount` Message",
      "service_level_category": 5,
      "sort_index": 4
    },
    {
      "code": 100,
      "name": "Merchant Economy",
      "transit_time": 9,
      "dutiable_transit_cost": 50,
      "charged_transit_cost": 75,
      "service_level_category": 7,
      "sort_index": 1
    },
    {
      "code": 101,
      "name": "Merchant Standard",
      "transit_time": 6,
      "delivery_date": "2017-03-17",
      "dutiable_transit_cost": 100,
      "service_level_category": 8,
      "sort_index": 2
    },
    {
      "code": 102,
      "name": "Merchant Express",
      "transit_time": 3,
      "dutiable_transit_cost": 100,
      "charged_transit_cost": 200,
      "charged_transit_cost_message": "10 Discount` Message",
      "service_level_category": 7,
      "sort_index": 3
    }
  ]
}'

<?php
$cart = new Cart();

// Order is Merchant Direct
$cart->setMerchantDirect(true);

// Setting some Shipping Address
$cart->setShippingAddress(
    new Address([
            'first_name' => 'John',
            'last_name' => 'Doe',
            'company' => 'My Biz',
            'address_1' => '10-123 1/2 MAIN STREET NW',
            'address_2' => 'MONTREAL QC H3Z 2Y7',
            'city' => 'Montreal',
            'country' => 'CA',
            'state' => 'Quebec',
            'zip' => 'H3Z 2Y7',
            'phone' => '1-514-888-9999',
            'email' => '[email protected]',
            'custom_1' => 'Custom Value 1',
            'custom_2' => 'Custom Value 2',
            'custom_3' => 'Custom Value 3',
            'tax_id' => '123456789',
        ]
    )
);

// Billing and Shipping Address can be the same
$cart->setBillingAddress($cart->getShippingAddress());

// Set the Merchant currency to USD
$cart->setMerchantCurrency('USD');

// Adding a single product
$cart->addProduct(
    new Product([
            'id' => '1766738',
            'name' => '576 #2 Pencils',
            'quantity' => 1,
            'price' => '37.25',
            'shipping' => '0.00',
            'country_of_origin' => 'US',
            'distribution_country' => 'US',
            'distribution_zip' => '',
            'product_transit' => 3,
            'custom_1' => '',
            'custom_2' => '',
            'custom_3' => '',
        ]
    )
);

// Set Merchant Direct Shipping Methods
$cart->setMerchantShippingMethods([
    new MerchantShippingMethod([
        "code" => 100,
        "name" => "Merchant Economy",
        "transit_time" => 9,
        "dutiable_transit_cost" => 50,
        "charged_transit_cost" => 75,
        "service_level_category" => 7,
        "sort_index" => 1
        ]
    ),
    new MerchantShippingMethod([
        "code" => 101,
        "name" => "Merchant Standard",
        "transit_time" => 6,
        "delivery_date" => "2017-03-17",
        "dutiable_transit_cost" => 100,
        "service_level_category" => 8,
        "sort_index" => 2
        ]
    ),
    new MerchantShippingMethod([
        "code" => 102,
        "name" => "Merchant Express",
        "transit_time" => 3,
        "dutiable_transit_cost" => 100,
        "charged_transit_cost" => 200,
        "charged_transit_cost_message" => "10 Discount` Message",
        "service_level_category" => 7,
        "sort_index" => 3
        ]
    ),
    new MerchantShippingMethod([
        "code" => 103,
        "name" => "Merchant Super Express",
        "transit_time" => 3,
        "dutiable_transit_cost" => 200,
        "charged_transit_cost" => 400,
        "charged_transit_cost_message" => "10 Discount` Message",
        "service_level_category" => 5,
        "sort_index" => 4
        ]
    )
]);

// Set a custom Merchant Shipping Method
$cart->setShippingMethod(new ShippingMethodOption(102));


$checkout = $checkoutClient->createCheckout($cart);

For Merchant Direct orders, the Shipping Address and the Merchant Shipping Methods are required.

Create Checkout Response (Merchant Direct)

{
    "checkout_id": "tzc596e67a2ebccd",
    "cart": {
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company": "My Biz",
            "address_1": "10-123 1/2 MAIN STREET NW",
            "address_2": "MONTREAL QC H3Z 2Y7",
            "city": "Montreal",
            "country": "CA",
            "state": "Quebec",
            "zip": "H3Z 2Y7",
            "phone": "1-514-888-9999",
            "email": "[email protected]",
            "custom_1": "Custom Value 1",
            "custom_2": "Custom Value 2",
            "custom_3": "Custom Value 3",
            "tax_id": "123456789"
        },
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company": "My Biz",
            "address_1": "10-123 1/2 MAIN STREET NW",
            "address_2": "MONTREAL QC H3Z 2Y7",
            "city": "Montreal",
            "country": "CA",
            "state": "Quebec",
            "zip": "H3Z 2Y7",
            "phone": "1-514-888-9999",
            "email": "[email protected]",
            "custom_1": "Custom Value 1",
            "custom_2": "Custom Value 2",
            "custom_3": "Custom Value 3",
            "tax_id": "123456789"
        },
        "domestic_shipping_charge": "0.00",
        "shipping_method": {
            "code": 102
        },
        "merchant_currency": "USD",
        "charge_duty_tax": true,
        "charge_loss_damage_protection": true,
        "products": [
            {
                "id": "1766738",
                "name": "576 #2 Pencils",
                "quantity": 1,
                "price": "37.25",
                "retail_price": "37.25",
                "shipping": "0.00",
                "country_of_origin": "US",
                "distribution_country": "US",
                "distribution_zip": "",
                "product_transit": 3,
                "custom_1": "",
                "custom_2": "",
                "custom_3": ""
            }
        ],
        "order_transit": 3,
        "retailer_order_number": "A-1234-001",
        "custom_order_1": "Custom Value 1",
        "custom_order_2": "Custom Value 2",
        "custom_order_3": "Custom Value 3",
        "customer_attributes": {
            "locale": "en_US",
            "ip": "8.8.8.8",
            "timezone": "America/Montreal"
        },
        "merchant_attributes": {
            "confirmation_uri": "",
            "merchant_direct": true
        },
        "merchant_shipping_methods": [
            {
                "code": 100,
                "name": "Merchant Economy",
                "transit_time": 9,
                "dutiable_transit_cost": 50,
                "charged_transit_cost": 75,
                "charged_transit_cost_message": null,
                "service_level_category": 7,
                "sort_index": 1
            },
            {
                "code": 101,
                "name": "Merchant Standard",
                "transit_time": 6,
                "dutiable_transit_cost": 100,
                "charged_transit_cost": 100,
                "charged_transit_cost_message": null,
                "service_level_category": 8,
                "sort_index": 2
            },
            {
                "code": 102,
                "name": "Merchant Express",
                "transit_time": 3,
                "dutiable_transit_cost": 100,
                "charged_transit_cost": 200,
                "charged_transit_cost_message": "10 Discount` Message",
                "service_level_category": 7,
                "sort_index": 3
            },
            {
                "code": 103,
                "name": "Merchant Super Express",
                "transit_time": 3,
                "dutiable_transit_cost": 200,
                "charged_transit_cost": 400,
                "charged_transit_cost_message": "10 Discount` Message",
                "service_level_category": 5,
                "sort_index": 4
            }
        ]
    },
    "available_shipping_methods": [
        {
            "code": 100,
            "name": "Merchant Economy",
            "amount": 108.68,
            "delivery_date": "2017-07-31"
        },
        {
            "code": 101,
            "name": "Merchant Standard",
            "amount": 144.9,
            "delivery_date": "2017-07-26"
        },
        {
            "code": 102,
            "name": "Merchant Express",
            "amount": 289.8,
            "delivery_date": "2017-07-21"
        },
        {
            "code": 103,
            "name": "Merchant Super Express",
            "amount": 579.6,
            "delivery_date": "2017-07-21"
        }
    ],
    "available_payment_methods": [
        {
            "code": "VISA",
            "name": "Visa",
            "type": "creditcard"
        },
        {
            "code": "MASTERCARD",
            "name": "Mastercard",
            "type": "creditcard"
        },
        {
            "code": "AMEX",
            "name": "Amex",
            "type": "creditcard"
        },
        {
            "code": "paypal_direct",
            "name": "PayPal",
            "type": "paypal"
        }
    ],
    "totals": {
        "currency": "CAD",
        "product_subtotals": [
            {
                "id": "1766738",
                "quantity": 1,
                "unit_price": "51.41",
                "retail_price": "51.41",
                "total_price": "51.41"
            }
        ],
        "subtotal": 51.41,
        "charges": {
            "shipping": 289.8,
            "duty": 0,
            "tax": 0,
            "ddp": false,
            "intl_processing_fee": 2.57,
            "remote_area_surcharge": "0.00",
            "loss_damage_protection": "6.88"
        },
        "total": "350.66"
    },
    "merchant_totals": {
        "currency": "USD",
        "product_subtotals": [
            {
                "id": "1766738",
                "quantity": 1,
                "unit_price": 37.25,
                "retail_price": "37.25",
                "total_price": 37.25
            }
        ],
        "subtotal": "37.25",
        "charges": {
            "shipping": "200.00",
            "duty": "0.00",
            "tax": "0.00",
            "ddp": false,
            "intl_processing_fee": 0,
            "remote_area_surcharge": 0,
            "loss_damage_protection": "4.75"
        },
        "total": "242.00"
    },
    "status": "Z",
    "order_id": null,
    "error": null,
    "extra": {
        "checkout_error_handling": true,
        "kount_uri_1": "http://checkout.stage2.bongo1.com/logo.htm?m=166800&s=tzc596e67a2ebccd",
        "kount_uri_2": "http://checkout.stage2.bongo1.com/logo.gif?m=166800&s=tzc596e67a2ebccd"
    }
}

HTTP Request

POST https://checkout.crossborder.fedex.com/v2/checkout

Request Parameters

Parameter	Type	Description
billing_address	Address	An Address object indicating the billing address.
shipping_address	Address	An Address object indicating the shipping address.
domestic_shipping_charge	string	Defines the cost of shipment on an order level from the vendor's location to a FedEx Cross Border Distribution Center.
shipping_method	ShippingMethodOption	A ShippingMethodOption object containing the selected shipping method.
merchant_currency	string	The currency the Merchant is settling in.
charge_loss_damage_protection	boolean	A boolean indicating whether or not the order will include Loss and Damage Protection.
charge_duty_tax	boolean	A boolean indicating whether or not the duties and taxes will be paid on checkout.
products	Product[]	An array of Product objects to be included in the order.
order_transit	integer	Defines the estimated domestic transit time (in Business Days) to the FedEx Cross Border Distribution Center.
retailer_order_number	string	A reference retailer or merchant order number.
custom_order_1	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_2	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_3	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
merchant_shipping_methods	MerchantShippingMethod[]	For Merchant Direct orders, an array of MerchantShippingMethod objects indicating the shipping methods available to the customer as defined by the merchant.
customer_attributes	CustomerAttributes	A CustomerAttributes object indicating the locale, timezone and IP address of the customer.
merchant_attributes	MerchantAttributes	A MerchantAttributes object indicating merchant-specific customizations.

Response Object

Attribute	Type	Description
checkout_id	string	The ID of the checkout process
cart	Cart	The current state of the Cart object
available_shipping_methods	AvailableShippingMethod[]	The list ot available shipping methods
available_payment_methods	AvailablePaymentMethod[]	The list of available payment methods
totals	CheckoutTotals	The checkout monetary totals expressed in the customer currency.
merchantTotals	CheckoutTotals	The checkout monetary totals expressed in the merchant currency.
status	string	The status of the checkout process
order_id	string	The Order ID, once an order has been placed.
error	CheckoutError	A detailed error object, if an error occurred, or null otherwise.
extra	CheckoutExtra	An associative array of additional information.

Get Checkout

Get Checkout Request

curl -X GET \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00 \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'x-fcb-partner-key: MyPartnerKey'

<?php

$checkoutId = 'tzc593919f92ed00';
$checkout = $checkoutClient->getCheckout($checkoutId);

Gets the current state of an existing Checkout process.

HTTP Request

GET https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process

Response Object

The response is a Checkout object.

Add Item

Add Item Request

curl -X POST \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00/items \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: MyPartnerKey' \
  -d '{
  "id": "1766739",
  "name": "576 #2 Pencils",
  "quantity": 1,
  "price": "37.25",
  "shipping": "0.00",
  "country_of_origin": "US",
  "distribution_country": "US",
}'

<?php

$checkoutId = 'tzc593919f92ed00';
$product = new Product([
    'id' => '1766739',
    'name' => '576 #2 Pencils',
    'quantity' => 1,
    'price' => '37.25',
    'shipping' => '0.00',
    'country_of_origin' => 'US',
    'distribution_country' => 'US',
    'distribution_zip' => '',
    'product_transit' => 3,
    'custom_1' => '',
    'custom_2' => '',
    'custom_3' => '',
    ]
);
$checkout = $checkoutClient->addItem($checkoutId, $product);

Add a new item to the shopping cart.

HTTP Request

POST https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}/items

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process

Request Body

Parameter	Type	Description
id	string	Product identifier code
name	string	Product name
quantity	integer	Product quantity
price	string	Product price
retail_price	string	Product retail price
shipping	string	Defines the cost of shipment on a product level from the vendor's location to a FedEx Cross Border Distribution Center.
country_of_origin	string	Product country of origin
distribution_country	string	Defines which country a sku will be fulfilled from, if the sku is not being sent to a FedEx Cross Border Distribution Center.
distribution_zip	string	Defines the specific international ZIP code a sku is being fulfilled from, if not being sent to a FedEx Cross Border Distribution Center.
product_transit	string	Transit time per product
custom_1	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.
custom_2	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.
custom_3	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.

Response Object

The response is a Checkout object.

Update Item

Update Item Request

curl -X PUT \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00/items/1766738 \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: MyPartnerKey' \
  -d '{
  "id": "1766738",
  "name": "576 #2 Pencils",
  "quantity": 10,
  "price": "37.25",
  "shipping": "0.00",
  "country_of_origin": "US",
  "distribution_country": "US",
}'

<?php

$checkoutId = 'tzc593919f92ed00';
$product = new Product([
    'id' => '1766738',
    'name' => '576 #2 Pencils',
    'quantity' => 10,
    'price' => '37.25',
    'shipping' => '0.00',
    'country_of_origin' => 'US',
    'distribution_country' => 'US',
    'distribution_zip' => '',
    'product_transit' => 3,
    'custom_1' => '',
    'custom_2' => '',
    'custom_3' => '',
    ]
);
$checkout = $checkoutClient->updateItem($checkoutId, $product);

Add a new item to the shopping cart.

HTTP Request

PUT https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}/items/{item_id}

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process
item_id	string	The ID of an existing item within the shopping cart

Request Body

The request body is a Product object.

Response Object

The response is a Checkout object.

Delete Item

Delete Item Request

curl -X DELETE \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00/items/1766738 \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'x-fcb-partner-key: MyPartnerKey'

<?php

$checkoutId = 'tzc593919f92ed00';
$productId = '1766738';
$checkoutClient->deleteItem($checkoutId, $productId);

Delete an existing item from the shopping cart.

HTTP Request

DELETE https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}/items/{item_id}

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process
item_id	string	The ID of an existing item within the shopping cart

Response Object

The response is a Checkout object.

Update Shipping Address

Update Shipping Address Request

curl -X PUT \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00/shippingAddress \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: MyPartnerKey'
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "company": "My Biz",
    "address_1": "10-123 1/2 MAIN STREET NW",
    "address_2": "MONTREAL QC H3Z 2Y7",
    "city": "Montreal",
    "country": "CA",
    "state": "Quebec",
    "zip": "H3Z 2Y7",
    "phone": "1-514-888-9999",
    "email": "[email protected]",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3",
    "tax_id": "123456789"
}'

<?php

$shippingAddress = new Address([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'company' => 'My Biz',
    'address_1' => '10-123 1/2 MAIN STREET NW',
    'address_2' => 'MONTREAL QC H3Z 2Y7',
    'city' => 'Montreal',
    'country' => 'CA',
    'state' => 'Quebec',
    'zip' => 'H3Z 2Y7',
    'phone' => '1-514-888-9999',
    'email' => '[email protected]',
    'custom_1' => 'Custom Value 1',
    'custom_2' => 'Custom Value 2',
    'custom_3' => 'Custom Value 3',
    'tax_id' => '123456789',
    ]
);

$checkoutId = 'tzc593919f92ed00';
$checkout = $checkoutClient->updateShippingAddress($checkoutId, $shippingAddress);

Set or update the shipping address.

HTTP Request

PUT https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}/shippingAddress

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process

Request Body

Parameter	Type	Description
first_name	string	Shipping name of the recipient
last_name	string	Shipping last name of the recipient
company	string	Name of the receiving company
address_1	string	First part of the address of the person or company receiving the shipment
address_2	string	Second part of the address of the person or company receiving the shipment
city	string	City name of the person or company receiving the shipment
country	string	Country Code of the person or company receiving the shipment
state	string	State name of the person or company receiving the shipment
zip	string	Postal code of the person or company receiving the shipment
phone	string	Telephone number of the person or company receiving the shipment
email	string	Email address of the person or company receiving the shipment
custom_1	string	Use this data field to add a description, categorization or any information you would like to include with the shipping address and have the same information returned to you when the order is confirmed.
custom_2	string	Use this data field to add a description, categorization or any information you would like to include with the shipping address and have the same information returned to you when the order is confirmed.
custom_3	string	Use this data field to add a description, categorization or any information you would like to include with the shipping address and have the same information returned to you when the order is confirmed.
tax_id	string	Tax ID of the person or company receiving the shipment

Response Object

The response is a Checkout object.

Update Billing Address

Update Billing Address Request

curl -X PUT \
  https://checkout.crossborder.fedex.com/v2/checkout/tzc593919f92ed00/billingAddress \
  -H 'accept: application/json' \
  -H 'authorization: Basic QVBJQ2xpZW50SUQ6QVBJU2VjcmV0' \
  -H 'content-type: application/json' \
  -H 'x-fcb-partner-key: 7625511ed3383939386558db5e52c99b'
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "company": "My Biz",
    "address_1": "10-123 1/2 MAIN STREET NW",
    "address_2": "MONTREAL QC H3Z 2Y7",
    "city": "Montreal",
    "country": "CA",
    "state": "Quebec",
    "zip": "H3Z 2Y7",
    "phone": "1-514-888-9999",
    "email": "[email protected]",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3",
    "tax_id": "123456789"
}'

<?php

$billingAddress = new Address([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'company' => 'My Biz',
    'address_1' => '10-123 1/2 MAIN STREET NW',
    'address_2' => 'MONTREAL QC H3Z 2Y7',
    'city' => 'Montreal',
    'country' => 'CA',
    'state' => 'Quebec',
    'zip' => 'H3Z 2Y7',
    'phone' => '1-514-888-9999',
    'email' => '[email protected]',
    'custom_1' => 'Custom Value 1',
    'custom_2' => 'Custom Value 2',
    'custom_3' => 'Custom Value 3',
    'tax_id' => '123456789',
    ]
);

$checkoutId = 'tzc593919f92ed00';
$checkout = $checkoutClient->updateBillingAddress($checkoutId, $billingAddress);

Set or update the billing address.

HTTP Request

PUT https://checkout.crossborder.fedex.com/v2/checkout/{checkout_id}/billingAddress

URL Parameters

Parameter	Type	Description
checkout_id	string	The ID of an existing Checkout process

Request Body

The request body is an Address object.

Response Object

The response is a Checkout object.

Merchant Direct API

Authentication

We support HTTP Basic Authentication with an API Client ID and an API Secret, as well as the OAuth2 Client Credential grant. API clients are free to use any of these two Authentication methods.

Server url: https://services.crossborder.fedex.com

Carrier credentials

POST {{server}}/carrier_credentials/v1/save

Request

Save carrier credentials request

{
  "carrier": 2,
  "expire_date": "2025-04-28 00:00:00",
  "credentials": {
    "account_name": "MYACCOUNT",
    "account_number": "xxxxxxx",
    "account_key": "xxxxxyyyyyzzzzzz",
    "account_meter": "123234243",
    "account_password": "ertertryurtt"
  }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Int	carrier	required	Carrier Id	2147483647	1,
Date	expire_date	required	Expiration date for the credentials	19	"2025-04-28 00:00:00"
Object	credentials	required	The carrier credentials	-

Response

Save carrier credentials response

{
    "token": "fxc665bc04f7114aa35eaaa885a0ba43"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	token	Always	Auth token	64	56a182bf373b7cb99283fbe92e1e0c3b,

Pack notification

POST {{server}}/md/v1/pack-notification

Request

Post pack notification

{
  "carrier_token": "56a182bf373b7cb99283fbe92e1e0c3b",
  "retail_order_number": "",
  "fxcb_order_number": "1000358613",

  "return_configuration": "Return Configuration",
  "insure": true,
  "insure_amount": 1.0,
  "qty_boxes": 1,
  "call_back_url": "Merchant Call back URL for Notifications",
  "customer_transaction_id": "FDX <CustomerTransactionId> field the merchant wants us to use when generating the AWB",
  "pickup_address": {
    "company_name": "Enterprise Name",
    "address1": "6 ave",
    "address2": "",
    "city": "ardmore",
    "state": "alberta",
    "zip_code": "T0A 0B0",
    "country": "CA",
    "phone": "131313123",
    "tax_id": ""
  },
  "consignor_address": {
    "company_name": "Enterprise Name",
    "address1": "6 ave",
    "address2": "",
    "city": "ardmore",
    "state": "alberta",
    "zip_code": "T0A 0B0",
    "country": "CA",
    "phone": "131313123",
    "tax_id": "as12313"
  },
  "boxes_info": [{
      "box_dim_uom": "CM",
      "box_weight": "5",
      "box_weight_uom": "KG",
      "box_length": "15",
      "box_width": "15",
      "box_height": "10",
      "items": [
        {
          "sku": "1499800906",
          "coo": "CH"
        }
      ]
    }
  ]
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String ( 64 )	carrier_token	Required		64	953806f1ac5a8dc34f79ab60124e072b,
String ( 100 )	retail_order_number	Optional		100	,
Big Int	fxcb_order_number	Required		"9223372036854770000"	1000358723,
Int	transit_method_code	Optional		4294967295	2
Object	return_configuration	Optional	What Return Configuration does merchant want included when generating label on merchant's behalf (Abandon in event of undeliverable, etc.).,
Boolean	insure	Optional		true / false	true,
Float	insure_amount	required if insure = true		8 int digits, 2 digits	1.0,
Int	qty_boxes	Required		4294967295	1,
String ( 255 )	call_back_url	Required		255	Merchant Call back URL for Notifications,
String ( 45 )	customer_transaction_id	Required		45	FDX field the merchant wants us to use when generating the AWB,
Object	pickup_address	Required		-
Object	consignor_address	Required		-
Object	boxes_info	Required		-
Array	items	Required		-

Response

Post pack notification response

{
    "id_pack_notification": "105",
    "documents_url": "{{server}}/dr/v1/get_documents/105"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Int	id_pack_notification	Always	Pack notification Id	4294967295	"9",
String	documents_url	Always	Url to get the documents	255	http://localhost:8085/dr/v1/get_documents/9

Cancel Pack notification

Cancel pack notification response

{
    "success": true,
    "id_pack_notification_log": "556"
}

DELETE {{server}}/md/v1/pack-notification/{{pack notification id}}

Response

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Boolean	success	Always	process result	true / false	"true"
Int	id_pack_notification_log	Always	Log id	4294967295	"1"

Item Refund

POST {{server}}/md/v1/item-refund

Request

Item Refund request

{
   "order_number": 351713,
   "charged_transit_cost": 30,
   "dutiable_transit_cost": 45,
   "user": "user",
   "merchant_note": "refund note",
   "items": [{"sku": "403-STD-STD", "quantity": 1}]
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
big int	order_number	Required		"9223372036854770000"	351713
float	charged_transit_cost	Required		8 int digits, 2 digits	30
float	dutiable_transit_cost	Optional		8 int digits, 2 digits	45
String	user	Required		65	"pancho"
String	merchant_note	Optional		255	"refund note"
array	items	Optional		-	-

Response

Item Refund response

{
    "success": true,
    "message": "Success"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Boolean	success	Always	process result	true / false	"false"
String	message	Always	process result	255	"Success"

Custom Refund

POST {{server}}/md/v1/custom-refund

Request

Custom Refund request

{
   "order_number": 351713,
   "custom_refund_amount": 30,
   "refund_reason_code": 45,
   "user": "user",
   "merchant_note": "refund note"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
big int	order_number	Required		"9223372036854770000"	351713
float	custom_refund_amount	Required		8 int digits, 2 digits	30
float	refund_reason_code	Optional		8 int digits	45
String	user	Optional		65	"pancho"
String	merchant_note	Optional		255	"refund note"

Response

Custom Refund response

{
    "success": true,
    "message": "Success"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Boolean	success	Always	process result	true / false	"true"
String	message	Always	process result	255	"Success"

Get Documents endpoint

GET {{server}}/dr/v1/get-documents/{{pack notification id}}

Response

Get Documents response

{
    "0": {
        "id_doc": 214,
        "doc_name": "LACEY-ACT-DOCUMENT",
        "url": "https://storage.bongous.com/s3bongous/5960eb829cc204ce42b4bc9d48041103.pdf",
        "format": "PDF"
    },
    "_links": {
        "self": {
            "href": "http://localhost:8085/dr/v1/get-documents/100"
        }
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
Array	documents	always	Array with documents

Dcouments array description

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
int	id_doc	always	Document identificator	10
string	doc_name	always	Document description	255
string	url	always	Url to get the document	255
string	format	always	Document format	5

Objects

This section describes all objects referenced in this API document.

Cart

The Cart object contains multiple input fields, such as the billing and shipping address, a product list, and additional order-level fields.

The checkout process can be started with an empty or partially-filled Cart object.

Parameter	Type	Description
billing_address	Address	An Address object indicating the billing address.
shipping_address	Address	An Address object indicating the shipping address.
domestic_shipping_charge	string	Defines the cost of shipment on an order level from the vendor's location to a FedEx Cross Border Distribution Center.
shipping_method	ShippingMethodOption	A ShippingMethodOption object containing the selected shipping method.
merchant_currency	string	The currency the Merchant is settling in.
charge_loss_damage_protection	boolean	A boolean indicating whether or not the order will include Loss and Damage Protection.
charge_duty_tax	boolean	A boolean indicating whether or not the duties and taxes will be paid on checkout.
products	Product[]	An array of Product objects to be included in the order.
order_transit	integer	Defines the estimated domestic transit time (in Business Days) to the FedEx Cross Border Distribution Center.
retailer_order_number	string	A reference retailer or merchant order number.
custom_order_1	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_2	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
custom_order_3	string	Use this data field to add a description, categorization or any information you would like to include with the order and have the same information returned to you when the order is confirmed.
merchant_shipping_methods	MerchantShippingMethod[]	For Merchant Direct orders, an array of MerchantShippingMethod objects indicating the shipping methods available to the customer as defined by the merchant.
customer_attributes	CustomerAttributes	A CustomerAttributes object indicating the locale, timezone and IP address of the customer.
merchant_attributes	MerchantAttributes	A MerchantAttributes object indicating merchant-specific customizations.

Checkout

The Checkout object is an output object that contains the current checkout state, including the contents of the shopping cart, the available shipping and payment methods, and all applicable monetary charges and totals.

Attribute	Type	Description
checkout_id	string	The ID of the checkout process
cart	Cart	The current state of the Cart object
available_shipping_methods	AvailableShippingMethod[]	The list ot available shipping methods
available_payment_methods	AvailablePaymentMethod[]	The list of available payment methods
totals	CheckoutTotals	The checkout monetary totals expressed in the customer currency.
merchantTotals	CheckoutTotals	The checkout monetary totals expressed in the merchant currency.
status	string	The status of the checkout process
order_id	string	The Order ID, once an order has been placed.
error	CheckoutError	A detailed error object, if an error occurred, or null otherwise.
extra	CheckoutExtra	An associative array of additional information.

Address

This object can contain either the shipping or the billing address information.

Parameter	Type	Description
first_name	string	First name
last_name	string	Last name
company	string	Associated company name
address_1	string	First part of the address of the person or company
address_2	string	Second part of the address of the person or company
city	string	City name
country	string	Two-letter country code (ISO 3166-1)
state	string	State name of the person or company
zip	string	Postal code of the person or company
phone	string	Telephone number of the person or company
email	string	Email address of the person or company
custom_1	string	Data field to add a description, categorization or any information to include with the address and have the same information returned when the order is confirmed.
custom_2	string	Data field to add a description, categorization or any information to include with the address and have the same information returned when the order is confirmed.
custom_3	string	Data field to add a description, categorization or any information to include with the address and have the same information returned when the order is confirmed.
tax_id	string	Tax ID of the person or company

AvailableShippingMethod

This object contains information associated to a particular shipping method that is available for the current order.

Parameter	Type	Description
code	integer	The code of the Shipping Method
name	string	The name of the Shipping Method
amount	string	The cost of the Shipping Method, expressed in the Merchant currency
delivery_date	string	The estimated date of arrival for this Shipping Method

MerchantShippingMethod

(Merchant Direct) This object describes a Shipping Method provided by the Merchant.

Parameter	Type	Description
code	integer	Merchant shipping method code
name	string	Merchant shipping name
transit_time	integer	Merchant shipping transit time (days)
dutiable_transit_cost	string	Merchant shipping dutiable transit cost
charged_transit_cost	string	Merchant shipping charge transit cost
charged_transit_cost_message	string	Merchant shipping charge transit cost Message
sort_index	string	Merchant sort index
service_level_category	string	FXCB service level category

ShippingMethodOption

This object can contain either the shipping or the billing address information.

Parameter	Type	Description
code	integer	The code of the selected Shipping Method

Product

This object describes a Product within the Cart object. All amounts are expressed in the Merchant currency.

Parameter	Type	Description
id	string	Product identifier code
name	string	Product name
quantity	integer	Product quantity
price	string	Product price
retail_price	string	Product retail price
shipping	string	Defines the cost of shipment on a product level from the vendor's location to a FedEx Cross Border Distribution Center.
country_of_origin	string	Product country of origin
distribution_country	string	Defines which country a sku will be fulfilled from, if the sku is not being sent to a FedEx Cross Border Distribution Center.
distribution_zip	string	Defines the specific international ZIP code a sku is being fulfilled from, if not being sent to a FedEx Cross Border Distribution Center.
product_transit	string	Transit time per product
custom_1	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.
custom_2	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.
custom_3	string	Data field to add a description, categorization or any information to include with the item(s) and have the same information returned when the order is confirmed.

CustomerAttributes

This object can contain additional customer information.

Parameter	Type	Description
locale	string	The customer locale (eg. en_CA)
timezone	string	The customer timezone (eg. America/Montreal)
ip	string	The customer IP

MerchantAttributes

This object can contain additional customer information.

Parameter	Type	Description
confirmation_uri	string	A confirmation URI to redirect to once an order has been placed
merchant_direct	string	A Y/N flag indicating whether or not the order is a Merchant Direct order

CheckoutTotals

This object can contain additional customer information.

Parameter	Type	Description
currency	string	A currency code in which all amounts are expressed
product_subtotals	ProductSubtotal[]	An array containing the subtotals for each product in the order
subtotal	string	The sum of all product subtotals
charges	CheckoutCharges	A CheckoutCharges object with additional order-level charges
total	string	The total monetary amount for this order

ProductSubtotal

This object contains subtotals amounts associated to a particular product.

Parameter	Type	Description
id	string	Product identifier code
quantity	int	Product quantity
unit_price	string	Unit price of this product
retail_price	string	Retail unit price of this product
total_price	string	The total monetary amount for this order

CheckoutCharges

This object can contain additional order-level charges.

Parameter	Type	Description
shipping	string	Shipping cost
duty	string	Duty cost
tax	string	Tax cost
ddp	boolean	true if the order will be DDP, false if DDU
intl_processing_fee	string	International processing fee
remote_area_surcharge	string	Additional remote area charges
loss_damage_protection	string	Additional lost and damage protection (if applicable)

CheckoutError

A detailed error object, if an error occurred, or null otherwise.

Parameter	Type	Description
code	integer	The error code
message	string	The error message
items	array	An array containing: id (the product id), name(the product name), and message(a product-level error message)

CheckoutExtra

An array containing additional order-level information.

Parameter	Type	Description
checkout_error_handling	boolean	An error handling strategy as specified by the Merchant
kount_uri_1	string	A tracking uri to collect customer information
kount_uri_2	string	A tracking uri to collect customer information

Merchant Direct Objects

Carrier credentials

FedEx Carrier credentials

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	account_name	required	Fedex account name	45	"FEDEX-MYACCOUNT",
String	account_number	required	Fedex account number	255	"491235624",
String	account_key	required	Fedex account key	64	"iwxxkqetzUzQeK8h",
String	account_meter	required	Fedex account meter	255	"111081774",
String	account_password	required	Fedex account password	64	"dDpQ8HZaaqtyE9ziT2voxaZ1r"

Pack Notification objects

pickup_address

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	contact_name	Optional		255	Enterprise Name,
String	company_name	Required if contact_name is empty		255
String	address1	Required		255	6 ave,
String	address2	Optional		255	,
String	city	Required		255	ardmore,
String	state	Required		255	alberta,
String	zip_code	Optional		10	T0A 0B0,
String	country	Required		3	CA,
String	phone	Optional		20	,
String	tax_id	Optional		45

consignor_address

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	contact_name	Optional		255	Enterprise Name,
String	company_name	Required if contact_name is empty		255
String	address1	Required		255	6 ave,
String	address2	Optional		255	,
String	city	Required		255	ardmore,
String	state	Required		255	alberta,
String	zip_code	Optional		10	T0A 0B0,
String	country	Required		3	CA,
String	phone	Optional		20	131313123,
String	tax_id	Optional		45	as12313

boxes_info

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String(2)	box_dim_uom	Required		2	CM,
Float	box_weight	Required		8 int digits, 2 digits	47483647.22,
String(2)	box_weight_uom	Required		2	KG,
Float	box_length	Required		8 int digits, 2 digits	47483647.22,
Float	box_width	Required		8 int digits, 2 digits	47483647.22,
Float	box_height	Required		8 int digits, 2 digits	47483647.22,

Item refund objects

items

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	sku	Required		65	OLY-1115,
String	coo	Required		2	CN

Errors

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request sucks.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Merchant Direct API errors

Save carrier credentials error response

Save carrier credentials error response

{
    "type": 2000,
    "title": "Error",
    "status": 500,
    "detail": "Carrier message: Authentication Failed"
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code	2147483647	422,
String	detail	always	Error description	255	"Failed Validation"
Array	validation_messages	optional	Array with the field and description	-

Post pack notification error response

Post pack notification error response

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": {
        "fxcb_order_number": [
            "We do not recognize this Order. Please check the ID and resubmit, or contact us for assistance."
        ]
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code	4294967295	422,
"Object / String	detail	always	Error description	255	"Failed Validation": "{id_pack_notification": "This pack notification ...}"
Array	validation_messages	optional	Array with the field and description

Cancel pack notification error response

Cancel pack notification error response

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": {
        "error": [
            {
                "code": 2084,
                "message": "We do not recognize this Pack Notification ID you are attempting to cancel. Please check the Pack Notification ID and resubmit, or contact us for assistance."
            }
        ]
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code		422,
"Object / String	detail	always	Error description	255	"Failed Validation": "{"id_pack_notification": "This pack notification ..."}"
Array	validation_messages	optional	Array with the field and description

Item Refund error response

Item Refund error response

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": {
        "error": [
            {
                "code": 2084,
                "message": "We do not recognize this Pack Notification ID you are attempting to cancel. Please check the Pack Notification ID and resubmit, or contact us for assistance."
            }
        ]
    },
    "validation_messages": {
      "fxcb_order_number": [
              "We do not recognize this Order. Please check the ID and resubmit, or contact us for assistance."
      ]
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code	4294967295	422,
"Object / String	detail	always	Error description	255	"Failed Validation": {order_number: You are attempting to issue a refund that exceeds the remaining funds associated with this order. Please enter a lower refund amount, or contact us for assistance.}"
Array	validation_messages	optional	Array with the field and description

Custom Refund error response

Custom Refund error response

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": {
        "error": [
            {
                "code": 2084,
                "message": "We do not recognize this Pack Notification ID you are attempting to cancel. Please check the Pack Notification ID and resubmit, or contact us for assistance."
            }
        ]
    },
    "validation_messages": {
      "fxcb_order_number": [
              "We do not recognize this Order. Please check the ID and resubmit, or contact us for assistance."
      ]
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code	4294967295	422,
"Object / String	detail	always	Error description	255	"Failed Validation": "{order_number": "You are attempting to issue a refund that exceeds the remaining funds associated with this order. Please enter a lower refund amount, or contact us for assistance.}"
Array	validation_messages	optional	Array with the field and description

Get documents error response

Get documents error response

{
    "message": "The document repository is not yet ready.",
    "_links": {
        "self": {
            "href": "http://localhost:8085/dr/v1/get-documents/103"
        }
    }
}

CHAR. TYPE / LENGTH	NAME	REQUIRED	DESCRIPTION	Length	EXAMPLE
String	type	always	Url for status code	255	"http//www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
String	title	always	Error tittle	255	"Unprocessable Entity",
Int	status	always	Status code		422,
"Object / String	detail	always	Error description	255	"Failed Validation": "{id_pack_notification": "This pack notification ...}"
Array	validation_messages	optional	Array with the field and description