Overview

The Zenkraft API is designed to be as standardized across all carriers as possible. The basic structure of each request is the same, with carrier-specific fields typically nested within special services.



OpenAPI 3 Specification

This API is also available in a machine-readable form as a OpenAPI 3 document

  • Basic authentication using a JWT token

  • RESTful using HTTP Verbs

  • JSON requests and responses


Test Tracking Numbers

The tracking numbers can be used below for testing purposes:

  • TEST100000001 - information sent to carrier
  • TEST100000002 - picked up
  • TEST100000003 - in transit
  • TEST100000004 - out for delivery
  • TEST100000005 - delivered
  • TEST100000006 - exception


Authentication

The Zenkraft API uses a bearer token to authenticate. If you do not have one, please contact support.

zkkey : your_api_key
Base URL
https://api.zenkraft.com

/shippingaccount POST

The /shippingaccount endpoint enables you to use your carrier account credentials to create a Shipping Acccount ID in the Zenkraft system. This is used for all future API calls listed below.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
shipping_account object required
auth object Carrier credentials which are specific to each carrier {'account_number': 'XXXXXXXX', 'meter_number': 'XXXXXXXX', 'key': 'XXXXXXXXXXXXXXXXXXXXXXXX', 'password': 'XXXXXXXXXXXXXXXXXXXXXXXX'}
billing_address object
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
carrier string Carrier slug required fedex
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
defaults object
currency string MOP CRC ARS LSL TMT GGP TOP HRK CVE SEK BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND KRW VUV PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
dim_units string Dimension units of the packages, inches or centimeters IN CM IN
label_type string Label Type PDF
packaging_type string Packaging Type your_packaging
service string Service Type domestic_standard
weight_units string Weight units of the packages, pounds or kilograms KG LB LB
location_id string Location ID 0d349ee54a8c4d0dbc61b1a3ac1ab1f4
name string Account name My FedEx test account
test boolean If you specify test flag and omit `auth` key, we'll try to create a shipping account with our test credentials for the carrier/country combination specified


Successful Response
Field Possible Values Example
shipping_account object
auth object Carrier credentials which are specific to each carrier {'account_number': 'XXXXXXXX', 'meter_number': 'XXXXXXXX', 'key': 'XXXXXXXXXXXXXXXXXXXXXXXX', 'password': 'XXXXXXXXXXXXXXXXXXXXXXXX'}
carrier string Carrier slug required fedex
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
defaults object required
currency string MOP CRC ARS LSL TMT GGP TOP HRK CVE SEK BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND KRW VUV PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
dim_units string Dimension units of the packages, inches or centimeters IN CM IN
label_type string Label Type PDF
packaging_type string Packaging Type your_packaging
service string Service Type domestic_standard
weight_units string Weight units of the packages, pounds or kilograms KG LB LB
id string Shipping account number required 5190163571408896
location_id string Location ID 0d349ee54a8c4d0dbc61b1a3ac1ab1f4
name string Account name My FedEx test account
test boolean If you specify test flag and omit `auth` key, we'll try to create a shipping account with our test credentials for the carrier/country combination specified


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key shipping_account_wrong_carrier shipping_account_not_found schema_validation_error master_test_shipping_account_not_found wrong_api_key schema_field_required unexpected_exception master_test_shipping_account_not_found
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required Master shipping account for fedex in US does not exist
Example Request / Response
{
    "shipping_account": {
        "name": "Test",
        "carrier": "fedex",
        "country": "US",
        "test" : true
    }
}
                curl --request POST \
--url https://api.zenkraft.com/shippingaccount \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "shipping_account": {
        "name": "Test",
        "carrier": "fedex",
        "country": "US",
        "test" : true
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "shipping_account": {
        "name": "Test",
        "carrier": "fedex",
        "country": "US",
        "test" : true
    }
}
url = "https://api.zenkraft.com/shippingaccount"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
    "shipping_account": {
        "name": "My FedEx test account",
        "carrier": "fedex",
        "country": "US",
        
        "test": false,
        "id": "567293923024"
    }
}

/rate POST

The rating endpoint is used to return estimated costs & time in transit data from the carrier. Zenkraft normalize this data across carriers providing a standardized date and cost format from the carriers (where the functionality is supported).

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
shipment object Definition of the shipment payload required
carrier string the carrier name required fedex
currency string MOP CRC ARS TMT LSL GGP TOP HRK SEK CVE BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND VUV KRW PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
debug boolean calls with debug=true will be logged
dim_units string Dimension units of the packages, inches or centimeters required IN CM IN
packages array required
height number height of the package according to units specified under dim_units 5
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
packaging string the packaging type required your_packaging your_packaging
recipient object Recipient of shiment required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
sender object Sender of shiment required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
service string if you specify the service type, you'll get rates only for this service fedex_ground
ship_date string shipping date 2021-06-07
shipping_account string Shipping account number required 5190163571408896
special_services array [saturday_delivery ]
test boolean calls created with test = true will be directed to the carrier test servers
type string outbound or return shipments outbound return outbound
weight_units string Weight units of the packages, pounds or kilograms required KG LB LB


Successful Response
Field Possible Values Example
rates array
currency string USD AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SPL SRD STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TVD TWD TZS UAH UGX UYU UZS VEF VND VUV WST XAF XCD XDR XOF XPF YER ZAR ZMW ZWD
delivery_day string Day of the week of the delivery. This field is optional depending on the carrier Mon
estimated_date string Number of days to ship. This field is optional depending on the carrier 2021-06-04
service_name string carrier supplied name of this service FedEx Freight
service_type string service slug which can be used when selecting a service in /ship fedex_ground
total_cost string total estimated price for this shipment 192.16
transit_days integer Number of days to ship. This field is optional depending on the carrier 3


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error ship_date_past carrier_exception wrong_api_key carrier_failed_connection schema_field_required unexpected_exception carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: The origin country code XX could not be found. Please check the country code.
Example Request / Response
{
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/rate \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}
url = "https://api.zenkraft.com/rate"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "rates": [
    {
      "currency": "USD",
      "service_name": "Express",
      "service_type": "economy",
      "total_cost": "192.16",
      "estimated_date": "2024-03-01",
      "delivery_day": "Mon",
      "transit_days": 3
    }
  ]
}

/ship POST

The shipping endpoint is used to book shipments with . It will return a shipping label and tracking number in the response.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
shipment object Definition of the shipment payload required
carrier string the carrier name required fedex
currency string MOP CRC ARS TMT LSL GGP TOP HRK CVE SEK BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND KRW VUV PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
debug boolean calls with debug=true will be logged
dim_units string Dimension units of the packages, inches or centimeters required IN CM IN
documents array
document string document content
document_type string file format of the document pdf
id string uploaded document ID
include_base64_label boolean If this is enabled, base64 label is returned
label_size string the shipping labels size 4x6
label_type string the label format of the shipping labels required GIF PDF ZPL JPG PNG PDF
notifications array
type string type of the notification needed email sms email
value string value of the notification notification1@example.com
packages array required
height number height of the package according to units specified under dim_units 5
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
packaging string the packaging type required your_packaging your_packaging
recipient object Recipient of shiment required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
references array
type string type of reference customer_reference
value string value of the reference ABC-000123
sender object Sender of shiment required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
service string the service type required fedex_ground
ship_date string shipping date 2021-06-07
shipping_account string Shipping account number required 5190163571408896
special_services array [saturday_delivery ]
test boolean calls created with test = true will be directed to the carrier test servers
type string outbound or return shipments outbound return outbound
weight_units string Weight units of the packages, pounds or kilograms required KG LB LB


Successful Response
Most important parts of the response:
  • tracking_number which can be used to track the shipments in the track endpoint
  • label for each package which needs to be printed and attached to the shipment
Field Possible Values Example
shipment object
context object this object can contain custom data returned by the carrier
costs object Additional information about packages
base_charge number gross amount 100
discounts number the cost of discounts applied 0
net_charge number net amount 80
surcharges number additional fees 0
taxes number the cost of taxes 20
id string shipment ID 1f02d12868a54ed88b6cb4dafaad325d
packages array
height number height of the package according to units specified under dim_units 5
label string base64 label if you specify include_base64_label flag in your request or an URL to the generated label
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
tracking_number string Tracking number of shipment 567293923024
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
shipping_documents object Additional information about packages
description string description of this customs item required Commercial Invoice
document string base64 document contents required
document_type string file format of the document required PDF
tracking_number string Tracking number of shipment 567293923024


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication invalid_phone_number schema_validation_error ship_date_past carrier_exception wrong_api_key carrier_failed_connection schema_field_required carrier_shipment_generation_failed unexpected_exception carrier_label_generation_failed carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: The origin country code XX could not be found. Please check the country code.
Example Request / Response
{
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/ship \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "shipment": {
        "carrier": "fedex",
        "currency": "GBP",
        "debug": true,
        "dim_units": "CM",
        "include_base64_label": true,
        "label_type": "PDF",
        "packages": [
            {
                "height": 1,
                "length": 1,
                "value": 1,
                "weight": 1,
                "width": 1
            }
        ],
        "packaging": "your_packaging",
        "recipient": {
            "city": "london",
            "company": "Zenkraft User",
            "country": "GB",
            "email": "testexample@gmail.com",
            "name": "Test User",
            "phone": "01222 555 555",
            "postal_code": "EC1R 4UG",
            "state": "",
            "street1": "1 Hardwick Street"
        },
        "sender": {
            "city": "Bath",
            "company": "TestCompany",
            "country": "GB",
            "email": "uk@testing.com",
            "name": "TestCompany Name",
            "phone": "",
            "postal_code": "EC2R 6PJ",
            "street1": "30 Moorgate"
        },
        "service": "economy",
        "ship_date": "2024-03-01",
        "shipping_account": "811195730",
        "test": true,
        "type": "outbound",
        "weight_units": "KG"
    }
}
url = "https://api.zenkraft.com/ship"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "shipment": {
    "carrier": "fedex",
    "shipping_account": "5190163571408896",
    "test": true,
    "debug": false,
    "ship_date": "2024-03-01",
    "type": "outbound",
    "service": "economy",
    "special_services": [
      "saturday_delivery"
    ],
    "packaging": "your_packaging",
    "dim_units": "IN",
    "weight_units": "LB",
    "currency": "USD",
    "sender": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27215",
      "country": "US"
    },
    "recipient": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27215",
      "country": "US"
    },
    "packages": [
      {
        "weight": 4.2,
        "value": 25,
        "length": 11,
        "width": 8.5,
        "height": 5,
        "tracking_number": "567293923024",
        "label": "string"
      }
    ],
    "label_type": "PDF",
    "include_base64_label": false,
    "references": [
      {
        "type": "customer_reference",
        "value": "ABC-000123"
      }
    ],
    "notifications": [
      {
        "type": "email",
        "value": "notification1@example.com"
      }
    ],
    "costs": {
      "base_charge": 100,
      "net_charge": 80,
      "taxes": 20,
      "surcharges": 0,
      "discounts": 0
    },
    "id": "1f02d12868a54ed88b6cb4dafaad325d",
    "tracking_number": "567293923024",
    "shipping_documents": [{
      "description": "Commercial Invoice",
      "document_type": "PDF",
      "document": "string"
    }],
    "context": {}
  }
}

/ship GET

This endpoint allows you to retrieve previously created shipments

GET Request Parameters
Field Possible Values Example
shipment_id object ID of the previously created shipment returned from POST on /ship required


Successful Response
Field Possible Values Example
shipment object
carrier string the carrier name fedex
created string when was this object created 2021-06-02T07:22:43.000
id string shipment ID 1f02d12868a54ed88b6cb4dafaad325d
label string base64 label
label_type string the label format of the shipping labels GIF PDF ZPL JPG PNG PDF
shipping_account string Shipping account number 5190163571408896
status string Standardized shipment status pending success success
tracking_number string Tracking number of shipment 567293923024
updated string when was this object updated 2021-06-02T13:10:02.000


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error carrier_exception wrong_api_key carrier_failed_connection schema_field_required carrier_no_shipment_found unexpected_exception carrier_label_generation_failed carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required DHL Global Forwarding API: Your shipment was rejected due to an unpaid invoice on your previous shipment. Contact DHL support to resolve the issue.
Example Request / Response
https://api.zenkraft.com/ship/b87ff34556ec4dba9e724963216d2dd7
                curl --request GET \
--url https://api.zenkraft.com/ship/b87ff34556ec4dba9e724963216d2dd7 \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/ship/b87ff34556ec4dba9e724963216d2dd7"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "shipment": {
    "carrier": "fedex",
    "shipping_account": "5190163571408896",
    "test": true,
    "debug": false,
    "ship_date": "2024-03-01",
    "type": "outbound",
    "service": "economy",
    "special_services": [
      "saturday_delivery"
    ],
    "packaging": "your_packaging",
    "dim_units": "IN",
    "weight_units": "LB",
    "currency": "USD",
    "sender": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27215",
      "country": "US"
    },
    "recipient": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27215",
      "country": "US"
    },
    "packages": [
      {
        "weight": 4.2,
        "value": 25,
        "length": 11,
        "width": 8.5,
        "height": 5,
        "tracking_number": "567293923024",
        "label": "string"
      }
    ],
    "label_type": "PDF",
    "include_base64_label": false,
    "references": [
      {
        "type": "customer_reference",
        "value": "ABC-000123"
      }
    ],
    "notifications": [
      {
        "type": "email",
        "value": "notification1@example.com"
      }
    ],
    "costs": {
      "base_charge": 100,
      "net_charge": 80,
      "taxes": 20,
      "surcharges": 0,
      "discounts": 0
    },
    "id": "1f02d12868a54ed88b6cb4dafaad325d",
    "tracking_number": "567293923024",
    "shipping_documents": [{
      "description": "Commercial Invoice",
      "document_type": "PDF",
      "document": "string"
    }],
    "context": {}
  }
}

/track POST

The track endpoint is used to track shipment status as it's being delivered.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
track object required
carrier string the carrier name required fedex
checkpoints boolean whether to include checkpoint events in the response or not
debug boolean calls with debug=true will be logged
locale string language used in the checkpoint response. Not all carriers support different languages ha_Latn_NE mg_MG mer_KE rwk_TZ es_NI pa_Arab_PK bg_BG so_ET es_US en_IN fr_MG sw_TZ zh_Hant_MO uz_Arab_AF es_DO es_ES et_EE gu_IN ar_AE fil_PH ar_LB en_PK es_GQ kk_Cyrl_KZ fr_BJ fr_SN es_GT en_MH gv_GB fr_GP zh_Hant_TW fr_ML zh_Hant en_AS en_BE sr_Cyrl bez_TZ nl_NL fr_MC luo_KE fr_RE eu_ES ga_IE es_UY ps_AF ar_TN kea_CV asa_TZ hi_IN fr_BL guz_KE ms_BN shi_Tfng_MA kde_TZ kam_KE fr_GA mfe_MU rof_TZ sr_Latn_BA ar_EG vi_VN en_MT mt_MT fr_RW sr_Cyrl_ME tzm_Latn_MA fr_MQ cs_CZ ses_ML te_IN pl_PL he_IL en_TT yo_NG jmc_TZ ur_IN it_IT ar_QA lg_UG pt_MZ ru_UA ar_OM naq_NA da_DK fr_KM sl_SI uk_UA uz_Arab nb_NO ko_KR ta_LK teo_UG bn_IN kab_DZ fi_FI pa_Guru az_Cyrl hu_HU pa_Guru_IN fr_CD kk_Cyrl mk_MK sr_Latn_ME zh_Hans_MO ar_SY hr_HR ebu_KE as_IN en_CA es_EC ii_CN es_SV es_CR ak_GH af_NA tr_TR es_PA ar_LY mr_IN tzm_Latn en_HK ha_Latn_NG sr_Latn de_CH fr_LU fr_CG ee_TG en_GB ms_MY ru_MD en_MU mas_KE en_VI ml_IN ne_IN es_PY gsw_CH en_MP uz_Latn nl_BE fr_CI el_GR nd_ZW rw_RW es_BO bo_CN kln_KE so_KE sk_SK en_US mas_TZ pt_PT uz_Cyrl_UZ de_DE ru_RU sr_Cyrl_BA cgg_UG teo_KE is_IS ki_KE ee_GH es_VE fr_CH ar_IQ sw_KE ar_KW it_CH en_AU en_IL es_PE zh_Hans_CN pt_GW fa_IR ca_ES shi_Latn_MA en_IE so_SO af_ZA hy_AM or_IN fr_BE ha_Latn zh_Hant_HK lt_LT my_MM om_ET bo_IN fr_TG es_AR ja_JP ar_DZ fr_CF ar_YE cy_GB es_419 so_DJ ar_SA am_ET zh_Hans_SG en_BZ kn_IN bs_BA bn_BD chr_US en_ZA sn_ZW xog_UG saq_KE kok_IN uz_Cyrl de_BE sq_AL sr_Latn_RS ur_PK ar_SD nyn_UG ka_GE es_PR th_TH de_AT de_LU be_BY fr_BF gl_ES bem_ZM nn_NO es_CO es_HN zh_Hans_HK sv_SE en_GU bm_ML khq_ML en_JM ff_SN az_Cyrl_AZ fr_CA pa_Arab ti_ER kl_GL ig_NG fr_DJ en_NZ haw_US id_ID km_KH ar_MA es_CL to_TO fr_TD en_PH lag_TZ ne_NP fo_FO zu_ZA kw_GB fr_MF ar_JO en_SG dav_KE rm_CH ar_BH zh_Hans en_ZW vun_TZ fr_GQ ha_Latn_GH ro_MD shi_Latn az_Latn_AZ en_NA fr_FR om_KE pt_BR el_CY luy_KE de_LI fr_GN lv_LV uz_Latn_UZ sr_Cyrl_RS ta_IN yue_Hant_HK fr_NE ro_RO es_MX ti_ET en_BW fr_BI fr_CM sv_FI shi_Tfng az_Latn si_LK sg_CF seh_MZ en_UM fa_AF en_US
refresh boolean whether to force calling live carrier API. By default, we might return a fresh result from the cache
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers
tracking_number string Tracking number of shipment required 567293923024
webhooks boolean whether to allow webhook functionality for this shipment


Successful Response
Field Possible Values Example
carrier string the carrier name fedex
checkpoints array
description string Delivered to a mailbox
status string the most recent important status description Delivered to a mailbox
time string 2021-06-07T10:46:07.000+1000
tracking_stage string the most recent important status standardized shipment stage CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DELIVERED SHIPMENT_VOIDED EXCEPTION DELIVERED
delivered boolean whether the shipment was successfully delivered
delivery_date string delivery date of this shipment 2021-06-07T00:00:00.000Z
estimated_delivery string estimated delivery date of this shipment 2021-06-07T00:00:00.000Z
locale string locale used in the checkpoint response. Not all carriers support different languages ha_Latn_NE mg_MG mer_KE rwk_TZ es_NI pa_Arab_PK bg_BG so_ET es_US en_IN fr_MG sw_TZ zh_Hant_MO uz_Arab_AF es_ES et_EE gu_IN ar_AE fil_PH ar_LB en_PK es_GQ kk_Cyrl_KZ fr_BJ fr_SN es_GT en_MH gv_GB fr_GP zh_Hant_TW fr_ML zh_Hant en_AS en_BE sr_Cyrl bez_TZ nl_NL fr_MC luo_KE fr_RE eu_ES ga_IE es_UY ps_AF ar_TN kea_CV asa_TZ hi_IN fr_BL guz_KE ms_BN shi_Tfng_MA kde_TZ kam_KE fr_GA mfe_MU rof_TZ sr_Latn_BA ar_EG vi_VN en_MT mt_MT fr_RW sr_Cyrl_ME tzm_Latn_MA fr_MQ cs_CZ ses_ML te_IN pl_PL he_IL en_TT yo_NG jmc_TZ ur_IN it_IT ar_QA lg_UG pt_MZ ru_UA ar_OM naq_NA da_DK fr_KM sl_SI es_DO uk_UA uz_Arab nb_NO ko_KR ta_LK teo_UG bn_IN kab_DZ fi_FI pa_Guru az_Cyrl hu_HU pa_Guru_IN fr_CD kk_Cyrl mk_MK sr_Latn_ME zh_Hans_MO ar_SY hr_HR ebu_KE as_IN en_CA es_EC ii_CN es_SV es_CR ak_GH af_NA tr_TR es_PA ar_LY mr_IN tzm_Latn en_HK ha_Latn_NG sr_Latn de_CH fr_LU fr_CG ee_TG so_DJ en_GB ms_MY ru_MD en_MU mas_KE en_VI ml_IN ne_IN es_PY gsw_CH en_MP uz_Latn nl_BE fr_CI el_GR nd_ZW rw_RW es_BO bo_CN kln_KE so_KE sk_SK en_US mas_TZ pt_PT uz_Cyrl_UZ de_DE ru_RU sr_Cyrl_BA cgg_UG teo_KE is_IS ki_KE ee_GH es_VE fr_CH ar_IQ sw_KE ar_KW it_CH en_AU en_IL es_PE zh_Hans_CN pt_GW fa_IR ca_ES shi_Latn_MA en_IE so_SO af_ZA hy_AM or_IN fr_BE ha_Latn zh_Hant_HK lt_LT my_MM om_ET bo_IN fr_TG es_AR ja_JP ar_DZ fr_CF ar_YE cy_GB es_419 ar_SA am_ET zh_Hans_SG en_BZ kn_IN bs_BA bn_BD chr_US en_ZA sn_ZW xog_UG saq_KE kok_IN uz_Cyrl de_BE sq_AL sr_Latn_RS ur_PK ar_SD nyn_UG ka_GE es_PR th_TH de_AT de_LU be_BY fr_BF gl_ES bem_ZM nn_NO es_CO es_HN zh_Hans_HK sv_SE en_GU bm_ML khq_ML en_JM ff_SN az_Cyrl_AZ fr_CA pa_Arab ti_ER kl_GL ig_NG fr_DJ en_NZ haw_US id_ID km_KH ar_MA es_CL to_TO fr_TD en_PH lag_TZ ne_NP fo_FO zu_ZA kw_GB fr_MF ar_JO en_SG dav_KE rm_CH ar_BH zh_Hans en_ZW vun_TZ fr_GQ ha_Latn_GH ro_MD shi_Latn az_Latn_AZ en_NA fr_FR om_KE pt_BR el_CY luy_KE de_LI fr_GN lv_LV uz_Latn_UZ sr_Cyrl_RS ta_IN yue_Hant_HK fr_NE ro_RO es_MX ti_ET en_BW fr_BI fr_CM sv_FI shi_Tfng az_Latn si_LK sg_CF seh_MZ en_UM fa_AF en_US
status string the most recent important status description Delivered to a mailbox
tracking_number string Tracking number of shipment 567293923024
tracking_stage string the most recent important status standardized shipment stage CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DELIVERED SHIPMENT_VOIDED EXCEPTION DELIVERED


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error carrier_exception wrong_api_key carrier_failed_connection schema_field_required carrier_no_shipment_found unexpected_exception carrier_no_shipment_found
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: No shipment found with tracking number: 567293923024
Example Request / Response
{
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/track \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
}
url = "https://api.zenkraft.com/track"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "carrier": "fedex",
  "delivered": true,
  "estimated_delivery": "2021-06-07T00:00:00.000Z",
  "delivery_date": "2021-06-07T00:00:00.000Z",
  "tracking_number": "567293923024",
  "status": "Delivered to a mailbox",
  "tracking_stage": "DELIVERED",
  "checkpoints": [
    {
      "description": "Delivered to a mailbox",
      "status": "Delivered to a mailbox",
      "tracking_stage": "DELIVERED",
      "time": "2021-06-07T10:46:07.000+1000"
    }
  ]
}

Batch tracking

You can pass several track objects into your API request to get results.
Request and response details are the same and can be checked here.

Example Request / Response
[
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  },
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  }
]
                curl --request POST \
--url https://api.zenkraft.com/track \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '[
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  },
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  }
]'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = [
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  },
  {
    "track": {
      "test":false,
      "carrier": "fedex",
      "shipping_account": 00000000000000,
      "tracking_number": "1Z7881280399212000"
    }
  }
]
url = "https://api.zenkraft.com/track"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
[
  {
    "carrier": "fedex",
    "delivered": true,
    "estimated_delivery": "2021-06-07T00:00:00.000Z",
    "delivery_date": "2021-06-07T00:00:00.000Z",
    "tracking_number": "567293923024",
    "status": "Delivered to a mailbox",
    "tracking_stage": "DELIVERED",
    "checkpoints": [
      {
        "description": "Delivered to a mailbox",
        "status": "Delivered to a mailbox",
        "tracking_stage": "DELIVERED",
        "time": "2021-06-07T10:46:07.000+1000"
      }
    ]
  },
  {
    "carrier": "fedex",
    "delivered": true,
    "estimated_delivery": "2021-06-07T00:00:00.000Z",
    "delivery_date": "2021-06-07T00:00:00.000Z",
    "tracking_number": "567293923024",
    "status": "Delivered to a mailbox",
    "tracking_stage": "DELIVERED",
    "checkpoints": [
      {
        "description": "Delivered to a mailbox",
        "status": "Delivered to a mailbox",
        "tracking_stage": "DELIVERED",
        "time": "2021-06-07T10:46:07.000+1000"
      }
    ]
  }
]

/cancel POST

The cancel endpoint allows you to cancel shipments with the carrier.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
cancel object required
carrier string the carrier name required fedex
checkpoints boolean whether to include checkpoint events in the response or not
debug boolean calls with debug=true will be logged
locale string language used in the checkpoint response. Not all carriers support different languages ha_Latn_NE mg_MG mer_KE rwk_TZ es_NI pa_Arab_PK bg_BG so_ET es_US en_IN fr_MG sw_TZ zh_Hant_MO uz_Arab_AF es_ES et_EE gu_IN ar_AE fil_PH ar_LB en_PK es_GQ kk_Cyrl_KZ fr_BJ fr_SN es_GT en_MH fa_AF gv_GB fr_GP zh_Hant_TW fr_ML zh_Hant en_AS en_BE sr_Cyrl bez_TZ nl_NL fr_MC luo_KE fr_RE eu_ES ga_IE es_UY ps_AF ar_TN kea_CV asa_TZ hi_IN fr_BL guz_KE ms_BN shi_Tfng_MA kde_TZ kam_KE fr_GA mfe_MU rof_TZ sr_Latn_BA ar_EG vi_VN en_MT mt_MT fr_RW sr_Cyrl_ME tzm_Latn_MA fr_MQ cs_CZ ses_ML te_IN pl_PL he_IL en_TT yo_NG jmc_TZ ur_IN it_IT ar_QA lg_UG pt_MZ ru_UA ar_OM naq_NA da_DK fr_KM sl_SI uk_UA uz_Arab nb_NO ko_KR ta_LK teo_UG bn_IN kab_DZ fi_FI pa_Guru az_Cyrl hu_HU pa_Guru_IN fr_CD kk_Cyrl mk_MK sr_Latn_ME zh_Hans_MO ar_SY hr_HR ebu_KE as_IN en_CA es_EC ii_CN es_SV es_CR ak_GH af_NA tr_TR es_PA ar_LY mr_IN tzm_Latn en_HK ha_Latn_NG sr_Latn de_CH fr_LU fr_CG ee_TG en_GB ms_MY ru_MD en_MU mas_KE en_VI ml_IN ne_IN es_PY gsw_CH en_MP uz_Latn nl_BE fr_CI el_GR nd_ZW rw_RW es_BO bo_CN kln_KE sk_SK en_US mas_TZ pt_PT uz_Cyrl_UZ de_DE ru_RU sr_Cyrl_BA cgg_UG teo_KE is_IS ki_KE ee_GH es_VE fr_CH ar_IQ sw_KE ar_KW it_CH en_AU en_IL es_PE zh_Hans_CN pt_GW fa_IR ca_ES shi_Latn_MA en_IE so_SO af_ZA hy_AM or_IN fr_BE ha_Latn zh_Hant_HK lt_LT my_MM om_ET bo_IN fr_TG es_AR ja_JP ar_DZ fr_CF ar_YE cy_GB es_419 so_DJ ar_SA am_ET zh_Hans_SG en_BZ kn_IN bs_BA bn_BD chr_US en_ZA sn_ZW xog_UG saq_KE kok_IN uz_Cyrl de_BE sq_AL sr_Latn_RS ur_PK ar_SD nyn_UG ka_GE es_PR th_TH de_AT de_LU be_BY fr_BF gl_ES bem_ZM nn_NO es_CO es_HN zh_Hans_HK sv_SE en_GU bm_ML khq_ML en_JM ff_SN az_Cyrl_AZ fr_CA pa_Arab ti_ER kl_GL ig_NG fr_DJ en_NZ haw_US id_ID km_KH ar_MA es_CL to_TO fr_TD en_PH lag_TZ ne_NP fo_FO zu_ZA kw_GB fr_MF ar_JO en_SG seh_MZ dav_KE rm_CH ar_BH zh_Hans en_ZW vun_TZ fr_GQ ha_Latn_GH ro_MD shi_Latn az_Latn_AZ en_NA fr_FR om_KE pt_BR el_CY luy_KE de_LI fr_GN lv_LV uz_Latn_UZ sr_Cyrl_RS ta_IN yue_Hant_HK fr_NE ro_RO es_MX ti_ET en_BW fr_BI fr_CM sv_FI shi_Tfng az_Latn si_LK sg_CF so_KE en_UM es_DO en_US
refresh boolean whether to force calling live carrier API. By default, we might return a fresh result from the cache
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers
tracking_number string Tracking number of shipment required 567293923024
webhooks boolean whether to allow webhook functionality for this shipment


Successful Response
Field Possible Values Example
success object
message string Message describing the action was performed successfully Success!


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error carrier_exception wrong_api_key carrier_failed_connection schema_field_required carrier_no_shipment_found unexpected_exception carrier_no_shipment_found
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: No shipment found with tracking number: 567293923024
Example Request / Response
{
    "cancel": {
        "shipping_account": "00000000000000",
        "carrier": "ups",
        "tracking_number": "1Z168R020399800319"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/cancel \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "cancel": {
        "shipping_account": "00000000000000",
        "carrier": "ups",
        "tracking_number": "1Z168R020399800319"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "cancel": {
        "shipping_account": "00000000000000",
        "carrier": "ups",
        "tracking_number": "1Z168R020399800319"
    }
}
url = "https://api.zenkraft.com/cancel"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "success": {
    "message": "The shipment has been canceled successfully"
  }
}

/pickup/availability POST

Find the time slots between the start_date and the end_date during which the carrier can pick up the specified shipments.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
pickup_availability object required
carrier string the carrier name required fedex
close_time string Reserved for future use 2021-06-04
currency string MOP CRC ARS TMT LSL GGP TOP HRK SEK CVE BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND VUV KRW PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
debug boolean calls with debug=true will be logged
description string
dim_units string Dimension units of the packages, inches or centimeters required IN CM IN
end_date string End of the range of dates to check required 2021-06-04
location object required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
location_type string description of the pickup location required front
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient required (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
ready_time string Reserved for future use 2021-06-04
shipments array required
packages array required
height number height of the package according to units specified under dim_units 5
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
recipient object Recipient of shiment
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
service string the service type fedex_ground
shipping_account string Shipping account number required 5190163571408896
start_date string Start of the range of dates to check required 2021-06-04
test boolean calls created with test = true will be directed to the carrier test servers
weight_units string Weight units of the packages, pounds or kilograms required KG LB LB


Successful Response
Field Possible Values Example
pickup_availability object
carrier string the carrier name required fedex
dates array
date string Pickup date 2021-06-04
earliest string The earliest time the shipments can be picked up 09:00
latest string The latest time the shipments can be picked up 18:00
debug boolean calls with debug=true will be logged
dim_units string Dimension units of the packages, inches or centimeters IN CM IN
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers
weight_units string Weight units of the packages, pounds or kilograms KG LB LB


Error Response
Field Possible Values Example
error object
code string Standardized error code required wrong_api_key carrier_throttling carrier_timeout carrier_unsupported_method missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication invalid_phone_number schema_validation_error ship_date_past carrier_exception carrier_failed_connection schema_field_required unexpected_exception carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: The origin country code XX could not be found. Please check the country code.
Example Request / Response
{
    "pickup_availability": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "service": "economy"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "weight_units": "LB",
        "start_date": "2024-03-01",
        "end_date": "2024-03-01"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/pickup/availability \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "pickup_availability": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "service": "economy"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "weight_units": "LB",
        "start_date": "2024-03-01",
        "end_date": "2024-03-01"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "pickup_availability": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "service": "economy"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "weight_units": "LB",
        "start_date": "2024-03-01",
        "end_date": "2024-03-01"
    }
}
url = "https://api.zenkraft.com/pickup/availability"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
    "pickup_availability": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "service": "economy"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "weight_units": "LB",
        "start_date": "2024-03-01",
        "end_date": "2024-03-01",
        "dates": [
            {
                "date" : "2021-06-30",
                "earliest": "09:00",
                "latest": "18:00"
            },
            {
                "date" : "2021-07-01",
                "earliest": "09:00",
                "latest": "18:00"
            },
            {
                "date" : "2021-07-02",
                "earliest": "09:00",
                "latest": "15:00"
            }
        ]
    }
}

/pickup POST

The pickup endpoint allows you to schedule pickups for one or more shipments.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
pickup object required
carrier string the carrier name required fedex
currency string MOP CRC ARS TMT LSL GGP TOP HRK CVE SEK BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND KRW VUV PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
debug boolean calls with debug=true will be logged
description string
dim_units string Dimension units of the packages, inches or centimeters required IN CM IN
location object required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
location_type string description of the pickup location required front
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient required (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
shipments array required
packages array required
height number height of the package according to units specified under dim_units 5
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
recipient object Recipient of shiment
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
service string the service type fedex_ground
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers
time object the date and time you want to create the pickup for. required
close_time string end of pickup time required 19:00
date string the date you want to create pickup for. required 2021-06-07
ready_time string start of pickup time required 12:30
weight_units string Weight units of the packages, pounds or kilograms required KG LB LB


Successful Response
Field Possible Values Example
pickup object
carrier string the carrier name required fedex
confirmation_number string reference number of this pickup. It can be used to cancel the pickup if the carrier allows it 123456789
currency string MOP CRC ARS TMT LSL GGP TOP HRK SEK CVE BAM WST MKD GTQ GNF AMD PYG NAD SVC RUB BGN IRR LKR ETB KWD PEN UYU PGK XPF ZWD KMF YER LYD IQD NIO VND VUV KRW PHP FKP BND GIP RWF MDL FJD THB HKD JOD NGN SPL INR BTN CNY HTG CDF SAR SCR CUC BZD DJF AWG AOA UGX SOS TVD ILS ISK JPY MNT SHP TJS CLP EGP ALL BWP MVR BIF MRU GHS KGS NZD LRD ZMW GYD PLN BHD SBD ERN PKR XDR LBP TZS XOF DZD UZS HNL CUP HUF RSD AUD COP KZT MAD GMD JMD MWK EUR MMK BBD SGD RON MYR XAF MUR BYN GEL PAB AZN USD BOB SDG MGA BMD ANG BSD VEF NPR TRY DOP IDR SZL IMP KPW STN KHR NOK SLL CZK DKK KES MZN SRD CHF GBP LAK XCD TTD UAH CAD KYD AFN QAR BRL BDT AED MXN JEP ZAR SYP TND OMR TWD
debug boolean calls with debug=true will be logged
description string
dim_units string Dimension units of the packages, inches or centimeters required IN CM IN
id string internal pickup ID cf8a402288034fd9941dc1efe22b0680
location object required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
location_type string description of the pickup location required front
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient required (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
shipments array required
packages array required
height number height of the package according to units specified under dim_units 5
length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height 11
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
width number width of the package according to units specified under dim_units 8.5
recipient object Recipient of shiment
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
service string the service type fedex_ground
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers
time object the date and time you want to create the pickup for. required
close_time string end of pickup time required 19:00
date string the date you want to create pickup for. required 2021-06-07
ready_time string start of pickup time required 12:30
weight_units string Weight units of the packages, pounds or kilograms required KG LB LB


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication invalid_phone_number schema_validation_error ship_date_past carrier_exception wrong_api_key carrier_failed_connection schema_field_required unexpected_exception carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message object Error message required FedEx API: The origin country code XX could not be found. Please check the country code.
Example Request / Response
{
    "pickup": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "recipient": {
                    "country": "US"
                },
                "service": "express_worldwide_p"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "time": {
            "ready_time": "09:45",
            "close_time": "16:45",
            "date": "2021-05-20"
        },
        "weight_units": "LB"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/pickup \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "pickup": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "recipient": {
                    "country": "US"
                },
                "service": "express_worldwide_p"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "time": {
            "ready_time": "09:45",
            "close_time": "16:45",
            "date": "2021-05-20"
        },
        "weight_units": "LB"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "pickup": {
        "carrier": "fedex",
        "debug": true,
        "dim_units": "IN",
        "location": {
            "city": "San Francisco",
            "company": "Test Company",
            "country": "US",
            "email": "test@example.com",
            "location_type": "business",
            "name": "Test Name",
            "phone": "+1 201-333-4444",
            "postal_code": "94105",
            "state": "NJ",
            "street1": "1 Market Street"
        },
        "shipments": [
            {
                "packages": [
                    {
                        "quantity": 1,
                        "weight": 3
                    }
                ],
                "recipient": {
                    "country": "US"
                },
                "service": "express_worldwide_p"
            }
        ],
        "shipping_account": 197299590,
        "test": true,
        "time": {
            "ready_time": "09:45",
            "close_time": "16:45",
            "date": "2021-05-20"
        },
        "weight_units": "LB"
    }
}
url = "https://api.zenkraft.com/pickup"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "pickup": {
    "confirmation_number": "123456789",
    "id": "cf8a402288034fd9941dc1efe22b0680",
    "carrier": "fedex",
    "shipping_account": "5190163571408896",
    "test": true,
    "debug": false,
    "description": "string",
    "currency": "USD",
    "dim_units": "IN",
    "weight_units": "LB",
    "location": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27215",
      "country": "US",
      "location_type": "front"
    },
    "shipments": [
      {
        "recipient": {
          "name": "Jack O'Rogers",
          "company": "Burlington Textiles Corp of America",
          "street1": "525 S. ZENKRAFT Ave",
          "street2": "suite 120",
          "email": "jrogers@example.com",
          "phone": "(336) 222-7000",
          "city": "Burlington",
          "state": "NC",
          "postal_code": "27215",
          "country": "US"
        },
        "packages": [
          {
            "weight": 4.2,
            "value": 25,
            "length": 11,
            "width": 8.5,
            "height": 5
          }
        ],
        "service": "fedex_ground"
      }
    ],
    "time": {
      "close_time": "19:00",
      "ready_time": "12:30",
      "date": "2021-06-07"
    }
  }
}

/dopu POST

The dopu endpoint is used to retrieve the list of possible drop off locations nearby.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
dopu object required
carrier string the carrier name required fedex
debug boolean calls with debug=true will be logged
location object required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers


Successful Response
Field Possible Values Example
locations array
city string Burlington
country string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
distance number how far is it from the location described in the request to this pickup location 1.3
distance_units string km
lat string latitude -79.43575121732864
lng string longitude 36.089788917096016
location_code string carrier assigned location ID A4415567
location_name string name of the business/post office United States Postal Service
location_type string the type of this pickup location post_office
postal_code string 27215
state string NC
street1 string 405 Maple Ave


Error Response
Field Possible Values Example
error object
code string Standardized error code required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error carrier_exception wrong_api_key carrier_failed_connection schema_field_required unexpected_exception carrier_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required FedEx API: Postal code specified is not in the correct format
Example Request / Response
{
    "dopu": {
        "carrier": "fedex",
        "location": {
            "city": "San Diego",
            "country": "US",
            "postal_code": "92131",
            "state": "CA",
            "street1": "1 Market Street"
        },
        "shipping_account": "673603996",
        "test": true
    }
}
                curl --request POST \
--url https://api.zenkraft.com/dopu \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "dopu": {
        "carrier": "fedex",
        "location": {
            "city": "San Diego",
            "country": "US",
            "postal_code": "92131",
            "state": "CA",
            "street1": "1 Market Street"
        },
        "shipping_account": "673603996",
        "test": true
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "dopu": {
        "carrier": "fedex",
        "location": {
            "city": "San Diego",
            "country": "US",
            "postal_code": "92131",
            "state": "CA",
            "street1": "1 Market Street"
        },
        "shipping_account": "673603996",
        "test": true
    }
}
url = "https://api.zenkraft.com/dopu"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "locations": [
    {
      "location_type": "post_office",
      "distance": 1.3,
      "distance_units": "km",
      "location_name": "United States Postal Service",
      "location_code": "A4415567",
      "city": "Burlington",
      "street1": "405 Maple Ave",
      "state": "NC",
      "postal_code": "27215",
      "country": "US",
      "lng": "36.089788917096016",
      "lat": "-79.43575121732864"
    }
  ]
}

/manifest POST

Manifesting allows you to notify the carrier that your shipments are ready for shipping/pickup.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
manifest object required
carrier string the carrier name required fedex
debug boolean calls with debug=true will be logged
shipping_account string Shipping account number required 5190163571408896
test boolean calls created with test = true will be directed to the carrier test servers


Successful Response
Field Possible Values Example
manifest object
costs object Additional information about packages
base_charge number gross amount 100
discounts number the cost of discounts applied
net_charge number net amount 80
surcharges number additional fees
taxes number the cost of taxes 20
id string carrier ID of this manifest which can be used in GET on /manifest/<manifest_id> 963681622636173689
shipping_documents object Additional information about packages
description string description of this customs item required Manifest
document string base64 document contents required
document_type string file format of the document required PDF


Error Response
Field Possible Values Example
error object
code string Standardized error code. If the code equals `carrier_large_manifest` you might retrieve manifest_id from the error detail required carrier_throttling carrier_unsupported_method carrier_timeout missing_api_key shipping_account_wrong_carrier shipping_account_not_found carrier_http_exception carrier_authentication schema_validation_error carrier_exception wrong_api_key carrier_failed_connection schema_field_required carrier_large_manifest unexpected_exception carrier_large_manifest
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required 963681622636173689
message string Error message required The manifest is too large and it's going to take around 15 to generate. Retry again later please
Example Request / Response
{
    "manifest": {
        "carrier": "fedex",
        "debug": true,
        "shipping_account": 40910738,
        "test": true,
        "tracking_numbers": [
            "33GKB500127801000961509",
            "111JD575508301000961502",
            "111JD575511501000961500"
        ]
    }
}
                curl --request POST \
--url https://api.zenkraft.com/manifest \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "manifest": {
        "carrier": "fedex",
        "debug": true,
        "shipping_account": 40910738,
        "test": true,
        "tracking_numbers": [
            "33GKB500127801000961509",
            "111JD575508301000961502",
            "111JD575511501000961500"
        ]
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "manifest": {
        "carrier": "fedex",
        "debug": true,
        "shipping_account": 40910738,
        "test": true,
        "tracking_numbers": [
            "33GKB500127801000961509",
            "111JD575508301000961502",
            "111JD575511501000961500"
        ]
    }
}
url = "https://api.zenkraft.com/manifest"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "manifest": {
    "id": "963681622636173689",
    "shipping_documents": [{
      "description": "Manifest",
      "document_type": "PDF",
      "document": "string"
    }],
    "costs": {
      "base_charge": 100,
      "net_charge": 80,
      "taxes": 20,
      "surcharges": 0,
      "discounts": 0
    }
  }
}

/manifest GET

This endpoint allows you to retrieve previously created manifests.

Successful Response
Field Possible Values Example
manifests array
carrier string the carrier name fedex
created string when was this object created 2021-06-02T07:22:43.000
id string carrier ID of this manifest which can be used in GET on /manifest/<manifest_id> 963681622636173689
shipping_account string Shipping account number 5190163571408896


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required Missing zkkey HTTP header containing your Zenkraft API key
Example Request / Response
https://api.zenkraft.com/manifest
                curl --request GET \
--url https://api.zenkraft.com/manifest \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/manifest"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "manifests": [
    {
      "carrier": "fedex",
      "created": "2021-06-02T07:22:43.000",
      "id": "963681622636173689",
      "shipping_account": "5190163571408896"
    }
  ]
}

/webhook POST

Webhooks provide you with a real-time view of your shipments.

1. Create a webhook configuration

In order to start using webhooks, you need to create a webhook configuration. You can find an example payload on the right side.

2. Receive a webhook

Now we will start sending tracking event updates as POST requests to your chosen address. The request will be formatted the same way as our track response

3. Verify a webhook

Webhooks can be verified by calculating a digital signature. Each webhook request includes a base64-encoded X-Zenkraft-Hmac-SHA256 header, which is generated using your API key along with the data sent in the request. Once you verify this signature, you can be sure the request came from us and you can continue your processing.

4. Response to a webhook

Your endpoint acknowledges that it received data by sending a 200 response. Any response outside of 200-range is considered an error. On our side, we have set a 5 second timeout. Any errors will be retried in a staggered manner over the course of the day.

Testing a Webhook

To test a webhook, run a local server or use a publicly available service such as Beeceptor. If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite or ngrok. The following URLs can't be endpoints for a webhook:

  • Localhost
  • Any URL ending in the word "internal"
  • Domains like www.example.com
  • Zenkraft domains such as api.zenkraft.com

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
webhook object required
api_version string The webhook version. Used for future compatibility v1
callback string URL of the receiving endpoint required https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508
debug boolean calls with debug=true will be logged
description string Webhook description
events array Events to receive. If left empty, it's assumed you want to receive all the events shipment.created shipment.delivered shipment.shipment_voided return.in_transit return.created shipment.out_for_delivery shipment.exception shipment.in_transit return.picked_up return.out_for_delivery return.delivered return.shipment_voided shipment.picked_up return.exception shipment.delivered
format string Currently only JSON is supported. Used for future compatibility json
headers array Headers that will be sent to the webhook callback.
name string Authorization
value string api_key
name string Webhook name
shipping_account_id integer 123
trigger_mode string checkpoint stage


Successful Response
Field Possible Values Example
webhook object
api_version string The webhook version. Used for future compatibility v1
callback string URL of the receiving endpoint required https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508
debug boolean calls with debug=true will be logged
description string Webhook description
events array Events to receive. If left empty, it's assumed you want to receive all the events shipment.created shipment.delivered shipment.shipment_voided return.in_transit return.created shipment.out_for_delivery shipment.exception shipment.in_transit return.picked_up return.out_for_delivery return.delivered return.shipment_voided shipment.picked_up return.exception shipment.delivered
format string Currently only JSON is supported. Used for future compatibility json
headers array Headers that will be sent to the webhook callback.
name string Authorization
value string api_key
id string ID of the subscription 484fe753dcda47a1b817456f3a10e38e
name string Webhook name
shipping_account_id integer 123
trigger_mode string checkpoint stage


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required Missing zkkey HTTP header containing your Zenkraft API key
Example Request / Response
{
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}
                curl --request POST \
--url https://api.zenkraft.com/webhook \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}
url = "https://api.zenkraft.com/webhook"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "webhook": {
    "name": "Test Webhook",
    "description": "Send delivery notifications",
    "events": ["shipment.out_for_delivery", "shipment.delivered"],
    "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
    "debug": false,
    "api_version": "v1",
    "format": "json",
    "id": "484fe753dcda47a1b817456f3a10e38e",
    "headers": [
      {
        "name": "Authorization",
        "value": "api_key"
      }
    ],
    "shipping_account_id": 123,
    "trigger_mode": "checkpoint"
  }
}


/webhook GET

This endpoint allows you to retrieve previously created webhooks.



Successful Response
Field Possible Values Example
webhooks array
api_version string The webhook version. Used for future compatibility v1
callback string URL of the receiving endpoint https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508
debug boolean calls with debug=true will be logged
description string Webhook description
events array Events to receive. If left empty, it's assumed you want to receive all the events shipment.created shipment.delivered shipment.shipment_voided return.in_transit return.created shipment.out_for_delivery shipment.exception shipment.in_transit return.picked_up return.out_for_delivery return.delivered return.shipment_voided shipment.picked_up return.exception shipment.delivered
format string Currently only JSON is supported. Used for future compatibility json
headers array Headers that will be sent to the webhook callback.
name string Authorization
value string api_key
id string ID of the subscription 484fe753dcda47a1b817456f3a10e38e
name string Webhook name
shipping_account_id integer 123
trigger_mode string checkpoint stage


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required Missing zkkey HTTP header containing your Zenkraft API key
Example Request / Response
https://api.zenkraft.com/webhook
                curl --request GET \
--url https://api.zenkraft.com/webhook \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/webhook"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "webhooks": [
    {
      "name": "Test Webhook",
      "description": "Send delivery notifications",
      "debug": false,
      "api_version": "v1",
      "format": "json",
      "events": [
        "shipment.delivered"
      ],
      "callback": "https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508",
      "headers": [
        {
          "name": "Authorization",
          "value": "api_key"
        }
      ],
      "shipping_account_id": 123,
      "trigger_mode": "checkpoint",
      "id": "484fe753dcda47a1b817456f3a10e38e"
    }
  ]
}


/webhook/{webhook_id} PUT

This endpoint allows you to put the webhook.

PUT Request Parameters
Field Possible Values Example
webhook object
api_version string The webhook version. Used for future compatibility v1
callback string URL of the receiving endpoint required https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508
debug boolean calls with debug=true will be logged
description string Webhook description
events array Events to receive. If left empty, it's assumed you want to receive all the events shipment.created shipment.delivered shipment.shipment_voided return.in_transit return.created shipment.out_for_delivery shipment.exception shipment.in_transit return.picked_up return.out_for_delivery return.delivered return.shipment_voided shipment.picked_up return.exception shipment.delivered
format string Currently only JSON is supported. Used for future compatibility json
headers array Headers that will be sent to the webhook callback.
name string Authorization
value string api_key
name string Webhook name
shipping_account_id integer 123
trigger_mode string checkpoint stage


Successful Response
Field Possible Values Example
webhook object
api_version string The webhook version. Used for future compatibility v1
callback string URL of the receiving endpoint required https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508
debug boolean calls with debug=true will be logged
description string Webhook description
events array Events to receive. If left empty, it's assumed you want to receive all the events shipment.created shipment.delivered shipment.shipment_voided return.in_transit return.created shipment.out_for_delivery shipment.exception shipment.in_transit return.picked_up return.out_for_delivery return.delivered return.shipment_voided shipment.picked_up return.exception shipment.delivered
format string Currently only JSON is supported. Used for future compatibility json
headers array Headers that will be sent to the webhook callback.
name string Authorization
value string api_key
id string ID of the subscription 484fe753dcda47a1b817456f3a10e38e
name string Webhook name
shipping_account_id integer 123
trigger_mode string checkpoint stage


Error Response
Field Possible Values Example
error object
code string Standardized error code. If the code equals `carrier_large_manifest` you might retrieve manifest_id from the error detail required missing_api_key shipping_account_wrong_carrier shipping_account_not_found webhook_not_found schema_validation_error wrong_api_key schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required No webhook exists with that ID
Example Request / Response
{
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}
                curl --request PUT \
--url https://api.zenkraft.com/webhook \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "{
    "webhook": {
        "name": "Test Webhook",
        "description": "Send delivery notifications",
        "events": ["shipment.out_for_delivery", "shipment.delivered"],
        "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
        "debug": false,
        "api_version": "v1",
        "format": "json",
        "headers": [
          {
            "name": "Authorization",
            "value": "api_key"
          }
        ],
        "shipping_account_id": 123,
        "trigger_mode": "checkpoint"
    }
}"

response = requests.request(url=url, method='PUT', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "webhook": {
    "name": "Test Webhook",
    "description": "Send delivery notifications",
    "events": ["shipment.out_for_delivery", "shipment.delivered"],
    "callback": "https://webhook.site/f263f99d-e822-4185-9ff8-f56789bc78c6",
    "debug": false,
    "api_version": "v1",
    "format": "json",
    "id": "484fe753dcda47a1b817456f3a10e38e",
    "headers": [
      {
        "name": "Authorization",
        "value": "api_key"
      }
    ],
    "shipping_account_id": 123,
    "trigger_mode": "checkpoint"
  }
}


/webhook/{webhook_id} DELETE

This endpoint allows you to delete the specific webhook.

DELETE Request Parameters
Field Possible Values Example
webhook_id object ID of the previously created webhook returned from POST on /webhook required


Successful Response
Field Possible Values Example
success object required
message string Message describing the action was performed successfully Success!


Error Response
Field Possible Values Example
error object
code string Standardized error code. If the code equals `carrier_large_manifest` you might retrieve manifest_id from the error detail required missing_api_key shipping_account_wrong_carrier shipping_account_not_found webhook_not_found schema_validation_error wrong_api_key schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required No webhook exists with that ID
Example Request / Response
https://api.zenkraft.com/webhook/7acd186c4bad4197ad36b918eff71c03
                curl --request GET \
--url https://api.zenkraft.com/webhook/7acd186c4bad4197ad36b918eff71c03 \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/webhook/7acd186c4bad4197ad36b918eff71c03"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "success": {
    "message": "Success!"
  }
}

/returns POST

These endpoints allow you to handle shipment returns. You need to have Return Methods set up in your admin interface in order to see the return methods in the response. Once you have the response, you need to identify the return option you want to use (e.g. dropoff at a specific location), and find its id (under return_methods->options->id). This id is sent in the follow up confirm request

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
return_methods object required
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
customer_id string 123456
debug boolean
location object required
city string the city of the recipient required Burlington
company string the company name of the recipient Burlington Textiles Corp of America
country string required AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
email string the email address of the recipient jrogers@example.com
name string the name of the recipient required Jack O'Rogers
phone string the phone number of the recipient (336) 222-7000
postal_code string the postal code / zip number of the recipient. Specific format depends on the country 27215
state string the state of the recipient NC
street1 string the first line of the street address of the recipient required 525 S. ZENKRAFT Ave
street2 string the second line of the street address of the recipient suite 120
street3 string the third line of the street address of the recipient suite 120
references array
type string type of reference customer_reference
value string value of the reference ABC-000123
return_lines array required
country_of_manufacture string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
hs_code string 444.333.2222
line_id string LINE-1234567890
product_name string Shoes
quantity integer quantity of this item in the package 1
reasons array
name string size
reasons object
name string required where
value string required toe
value string too_small
sku string SKU-123455666
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
test boolean


Successful Response
Field Possible Values Example
return_lines array
country_of_manufacture string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
hs_code string 444.333.2222
line_id string LINE-1234567890
product_name string Shoes
quantity integer quantity of this item in the package 1
reasons array
name string size
reasons object
name string required where
value string required toe
value string too_small
sku string SKU-123455666
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2


Error Response
Example Request / Response
{
  "return_methods": {
    "test": true,
    "debug": true,
    "customer_id": "123456",
    "location": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27415",
      "country": "US"
    },
    "references": [
      {
        "type": "customer_reference",
        "value": "ABC-000123"
      }
    ],
    "return_lines": [
      {
        "quantity": 1,
        "value": 25,
        "weight": 4.2,
        "product_name": "Shoes",
        "line_id": "LINE-1234567890",
        "hs_code": "444.333.2222",
        "sku": "SKU-123455666",
        "country_of_manufacture": "US",
        "reasons": [
          {
            "name": "wrong_size",
            "value": "Wrong Size",
            "reasons": {
              "name": "to_small",
              "value": "Too Small"
            }
          }
        ]
      }
    ]
  }
}
                curl --request POST \
--url https://api.zenkraft.com/returns \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
  "return_methods": {
    "test": true,
    "debug": true,
    "customer_id": "123456",
    "location": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27415",
      "country": "US"
    },
    "references": [
      {
        "type": "customer_reference",
        "value": "ABC-000123"
      }
    ],
    "return_lines": [
      {
        "quantity": 1,
        "value": 25,
        "weight": 4.2,
        "product_name": "Shoes",
        "line_id": "LINE-1234567890",
        "hs_code": "444.333.2222",
        "sku": "SKU-123455666",
        "country_of_manufacture": "US",
        "reasons": [
          {
            "name": "wrong_size",
            "value": "Wrong Size",
            "reasons": {
              "name": "to_small",
              "value": "Too Small"
            }
          }
        ]
      }
    ]
  }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
  "return_methods": {
    "test": true,
    "debug": true,
    "customer_id": "123456",
    "location": {
      "name": "Jack O'Rogers",
      "company": "Burlington Textiles Corp of America",
      "street1": "525 S. ZENKRAFT Ave",
      "street2": "suite 120",
      "email": "jrogers@example.com",
      "phone": "(336) 222-7000",
      "city": "Burlington",
      "state": "NC",
      "postal_code": "27415",
      "country": "US"
    },
    "references": [
      {
        "type": "customer_reference",
        "value": "ABC-000123"
      }
    ],
    "return_lines": [
      {
        "quantity": 1,
        "value": 25,
        "weight": 4.2,
        "product_name": "Shoes",
        "line_id": "LINE-1234567890",
        "hs_code": "444.333.2222",
        "sku": "SKU-123455666",
        "country_of_manufacture": "US",
        "reasons": [
          {
            "name": "wrong_size",
            "value": "Wrong Size",
            "reasons": {
              "name": "to_small",
              "value": "Too Small"
            }
          }
        ]
      }
    ]
  }
}
url = "https://api.zenkraft.com/returns"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "return_lines": [
    {
      "quantity": 1,
      "value": 25,
      "weight": 4.2,
      "product_name": "Shoes",
      "line_id": "LINE-1234567890",
      "hs_code": "444.333.2222",
      "sku": "SKU-123455666",
      "country_of_manufacture": "US",
      "reasons": [
        {
          "name": "wrong_size",
          "value": "Wrong Size",
          "reasons": {
            "name": "to_small",
            "value": "Too Small"
          }
        }
      ]
    }
  ],
  "return_methods": [
    {
      "id": "f936964c2a7745dc8e0f2d055efabd50",
      "carrier": "fedex",
      "carrier_logo": "https://test-cdn.zenkraft.com/static/images/carriers/fedex.png",
      "carrier_name": "FedEx",
      "method_name": "FedEx Drop Off",
      "type": "drop_off",
      "options": [
        {
          "city": "Livingston",
          "country": "US",
          "distance": 0.62,
          "id": "500bd31de3204d11b549df947ac1f695_1",
          "lat": "40.794128",
          "lng": "-74.314625",
          "location_id": "ANFCV",
          "location_name": "FedEx OnSite",
          "operational_hours": {
            "MON": {
              "open": "08:00",
              "close": "22:00"
            },
            "TUE": {
              "open": "08:00",
              "close": "22:00"
            },
            "WED": {
              "open": "08:00",
              "close": "22:00"
            },
            "THU": {
              "open": "08:00",
              "close": "22:00"
            },
            "FRI": {
              "open": "08:00",
              "close": "22:00"
            },
            "SAT": {
              "open": "08:00",
              "close": "22:00"
            },
            "SUN": {
              "open": "08:00",
              "close": "22:00"
            }
          },
          "postal_code": "7039",
          "state": "NJ",
          "street1": "45 S Livingston Ave"
        }
      ]
    }
  ]
}


/returns GET

This endpoint allows you to retrieve previously created returns

GET Request Parameters
Field Possible Values Example
start_date object Start date filter
end_date object End date filter
search object Filter by tracking, reference and confirmation numbers of related shipment or pickup objects
return_method object Tracking number filter
customer_id object Customer ID filter
order_id object Order ID filter
status object Shipment status filter
custom object Custom pair filter
page object Page number
pageSize object Return items amount per page


Successful Response
Field Possible Values Example
returns array
created string when was this object created 2021-06-02T07:22:43.000
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
customer_id string 123456
id string 2ff7047526e64a10a3e952680aca7e81
pickup object
confirmation_number string reference number of this pickup. It can be used to cancel the pickup if the carrier allows it required 123456789
id string required 7acd186c4bad4197ad36b918eff71c03
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
return_method object
carrier string required fedex
carrier_logo string required https://test-cdn.zenkraft.com/static/images/carriers/fedex.png
carrier_name string required FedEx
cost object required
carrier_charge number required 4.99
customer_charge number required 4.99
id string required f936964c2a7745dc8e0f2d055efabd50
method_name string required FedEx Drop Off
return_charge number required 4.99
type string required pickup drop_off drop_off
shipment object
id string required 7acd186c4bad4197ad36b918eff71c03
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
status string the most recent important status description required Delivered to a mailbox
tracking_number string Tracking number of shipment required 567293923024
Example Request / Response
https://api.zenkraft.com/returns
                curl --request GET \
--url https://api.zenkraft.com/returns \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/returns"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
[
  {
    "id": "2ff7047526e64a10a3e952680aca7e81",
    "customer_id": "123456",
    "created": "2021-06-02T07:22:43.000",
    "return_method": {
      "id": "f936964c2a7745dc8e0f2d055efabd50",
      "carrier": "fedex",
      "carrier_logo": "https://test-cdn.zenkraft.com/static/images/carriers/fedex.png",
      "carrier_name": "FedEx",
      "method_name": "FedEx Drop Off",
      "type": "drop_off",
      "cost": {
        "carrier_charge": 4.99,
        "customer_charge": 4.99
      },
      "return_charge": 4.99
    },
    "pickup": {
      "id": "7acd186c4bad4197ad36b918eff71c03",
      "confirmation_number": "123456789",
      "reference_number": "567293923024"
    },
    "shipment": {
      "id": "7acd186c4bad4197ad36b918eff71c03",
      "tracking_number": "567293923024",
      "reference_number": "567293923024",
      "status": "Delivered to a mailbox"
    }
  }
]


/returns/{return_id} GET

This endpoint allows you to retrieve specific return details.

GET Request Parameters
Field Possible Values Example
return_id object return ID required


Successful Response
Field Possible Values Example
created string when was this object created required 2021-06-02T07:22:43.000
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
customer_id string required CUST-99sa6
id string required 7acd186c4bad4197ad36b918eff71c03
order_id string ORD-568
pickup object
confirmation_number string reference number of this pickup. It can be used to cancel the pickup if the carrier allows it required 123456789
id string required 7acd186c4bad4197ad36b918eff71c03
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
return_lines array required
country_of_manufacture string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
hs_code string 444.333.2222
line_id string LINE-1234567890
product_name string Shoes
quantity integer quantity of this item in the package 1
reasons array
name string size
reasons object
name string required where
value string required toe
value string too_small
sku string SKU-123455666
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
return_method object required
carrier string required fedex
carrier_logo string required https://test-cdn.zenkraft.com/static/images/carriers/fedex.png
carrier_name string required FedEx
cost object required
carrier_charge number required 4.99
customer_charge number required 4.99
id string required f936964c2a7745dc8e0f2d055efabd50
method_name string required FedEx Drop Off
return_charge number required 4.99
type string required pickup drop_off drop_off
shipment object required
id string required
label string base64 label required
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
status string the most recent important status description required Delivered to a mailbox
tracking_number string Tracking number of shipment required 567293923024
Example Request / Response
https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03
                curl --request GET \
--url https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03 \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "id": "7acd186c4bad4197ad36b918eff71c03",
  "customer_id": "123456",
  "created": "2021-06-02T07:22:43.000",
  "return_lines": [
    {
      "quantity": 1,
      "value": 25,
      "weight": 4.2,
      "product_name": "Shoes",
      "line_id": "LINE-1234567890",
      "hs_code": "444.333.2222",
      "sku": "SKU-123455666",
      "country_of_manufacture": "US",
      "reasons": [
        {
          "name": "wrong_size",
          "value": "Wrong Size",
          "reasons": {
            "name": "to_small",
            "value": "Too Small"
          }
        }
      ]
    }
  ],
  "return_method": {
    "id": "f936964c2a7745dc8e0f2d055efabd50",
    "carrier": "fedex",
    "carrier_logo": "https://test-cdn.zenkraft.com/static/images/carriers/fedex.png",
    "carrier_name": "FedEx",
    "method_name": "FedEx Drop Off",
    "type": "drop_off",
    "cost": {
      "carrier_charge": 4.99,
      "customer_charge": 4.99
    },
    "return_charge": 4.99
  },
  "pickup": {
    "id": "7acd186c4bad4197ad36b918eff71c03",
    "confirmation_number": "123456789",
    "reference_number": "567293923024"
  },
  "shipment": {
    "id": "f936964c2s77a2342af055efabd79",
    "tracking_number": "567293923024",
    "reference_number": "567293923024",
    "status": "Delivered to a mailbox",
    "label": "label base64"
  }
}


/returns/{return_id} PATCH

This endpoint allows you to update some specific return details.
If you pass 'SHIPMENT_VOIDED' shipment status to the request payload, shipment and pickup will be cancelled.

PATCH Request Parameters
Field Possible Values Example
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
shipment object
status string the most recent important status description Delivered to a mailbox


Successful Response
Field Possible Values Example
created string when was this object created required 2021-06-02T07:22:43.000
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
customer_id string required CUST-99sa6
id string required 7acd186c4bad4197ad36b918eff71c03
order_id string ORD-568
pickup object
confirmation_number string reference number of this pickup. It can be used to cancel the pickup if the carrier allows it required 123456789
id string required 7acd186c4bad4197ad36b918eff71c03
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
return_lines array required
country_of_manufacture string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
hs_code string 444.333.2222
line_id string LINE-1234567890
product_name string Shoes
quantity integer quantity of this item in the package 1
reasons array
name string size
reasons object
name string required where
value string required toe
value string too_small
sku string SKU-123455666
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
return_method object required
carrier string required fedex
carrier_logo string required https://test-cdn.zenkraft.com/static/images/carriers/fedex.png
carrier_name string required FedEx
cost object required
carrier_charge number required 4.99
customer_charge number required 4.99
id string required f936964c2a7745dc8e0f2d055efabd50
method_name string required FedEx Drop Off
return_charge number required 4.99
type string required pickup drop_off drop_off
shipment object required
id string required
label string base64 label required
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
status string the most recent important status description required Delivered to a mailbox
tracking_number string Tracking number of shipment required 567293923024
Example Request / Response
{
  "custom": [
    {
      "name": "refunded",
      "value": true
    }
  ],
  "shipment": {
    "status": "IN_TRANSIT"
  }
}
                curl --request PATCH \
--url https://api.zenkraft.com/returns \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
  "custom": [
    {
      "name": "refunded",
      "value": true
    }
  ],
  "shipment": {
    "status": "IN_TRANSIT"
  }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "{
  "custom": [
    {
      "name": "refunded",
      "value": true
    }
  ],
  "shipment": {
    "status": "IN_TRANSIT"
  }
}"

response = requests.request(url=url, method='PATCH', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "id": "7acd186c4bad4197ad36b918eff71c03",
  "customer_id": "123456",
  "created": "2021-06-02T07:22:43.000",
  "return_lines": [
    {
      "quantity": 1,
      "value": 25,
      "weight": 4.2,
      "product_name": "Shoes",
      "line_id": "LINE-1234567890",
      "hs_code": "444.333.2222",
      "sku": "SKU-123455666",
      "country_of_manufacture": "US",
      "reasons": [
        {
          "name": "wrong_size",
          "value": "Wrong Size",
          "reasons": {
            "name": "to_small",
            "value": "Too Small"
          }
        }
      ]
    }
  ],
  "return_method": {
    "id": "f936964c2a7745dc8e0f2d055efabd50",
    "carrier": "fedex",
    "carrier_logo": "https://test-cdn.zenkraft.com/static/images/carriers/fedex.png",
    "carrier_name": "FedEx",
    "method_name": "FedEx Drop Off",
    "type": "drop_off",
    "cost": {
      "carrier_charge": 4.99,
      "customer_charge": 4.99
    },
    "return_charge": 4.99
  },
  "pickup": {
    "id": "7acd186c4bad4197ad36b918eff71c03",
    "confirmation_number": "123456789",
    "reference_number": "567293923024"
  },
  "shipment": {
    "id": "f936964c2s77a2342af055efabd79",
    "tracking_number": "567293923024",
    "reference_number": "567293923024",
    "status": "Delivered to a mailbox",
    "label": "label base64"
  }
}


/returns/{return_id} DELETE

This endpoint allows you to cancel and delete the specific return.

DELETE Request Parameters
Field Possible Values Example
return_id object return ID required


Successful Response
Field Possible Values Example
success object required
message string Message describing the action was performed successfully Success!
Example Request / Response
https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03
                curl --request GET \
--url https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03 \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/returns/7acd186c4bad4197ad36b918eff71c03"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "success": {
    "message": "Success!"
  }
}


/returns/confirm POST

This endpoint allows you to confirm returns creation.

POST Request Parameters
Field Possible Values Example
return_methods array 7acd186c4bad4197ad36b918eff71c03


Successful Response
Field Possible Values Example
returns array
created string when was this object created 2021-06-02T07:22:43.000
custom array Custom context attached to the return
name string Name of the custom field refunded
value object The value of the custom field - can be any type of object true
customer_id string CUST-99sa6
id string 7acd186c4bad4197ad36b918eff71c03
order_id string ORD-568
pickup object
confirmation_number string reference number of this pickup. It can be used to cancel the pickup if the carrier allows it required 123456789
id string required 7acd186c4bad4197ad36b918eff71c03
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
return_lines array
country_of_manufacture string AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW US
hs_code string 444.333.2222
line_id string LINE-1234567890
product_name string Shoes
quantity integer quantity of this item in the package 1
reasons array
name string size
reasons object
name string required where
value string required toe
value string too_small
sku string SKU-123455666
value number value of the package according to currency specified 25
weight number weight of the package according to units specified under weight_units 4.2
return_method object
carrier string required fedex
carrier_logo string required https://test-cdn.zenkraft.com/static/images/carriers/fedex.png
carrier_name string required FedEx
cost object required
carrier_charge number required 4.99
customer_charge number required 4.99
id string required f936964c2a7745dc8e0f2d055efabd50
method_name string required FedEx Drop Off
return_charge number required 4.99
type string required pickup drop_off drop_off
shipment object
id string required
label string base64 label required
reference_number string some carriers allow you to track either by the tracking number or the reference number required 567293923024
status string the most recent important status description required Delivered to a mailbox
tracking_number string Tracking number of shipment required 567293923024
Example Request / Response
{
  "return_methods": [
    "7acd186c4bad4197ad36b918eff71c03"
  ]
}
                curl --request POST \
--url https://api.zenkraft.com/returns \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
  "return_methods": [
    "7acd186c4bad4197ad36b918eff71c03"
  ]
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
  "return_methods": [
    "7acd186c4bad4197ad36b918eff71c03"
  ]
}
url = "https://api.zenkraft.com/returns"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
[
  {
    "id": "7acd186c4bad4197ad36b918eff71c03",
    "customer_id": "123456",
    "created": "2021-06-02T07:22:43.000",
    "return_lines": [
      {
        "quantity": 1,
        "value": 25,
        "weight": 4.2,
        "product_name": "Shoes",
        "line_id": "LINE-1234567890",
        "hs_code": "444.333.2222",
        "sku": "SKU-123455666",
        "country_of_manufacture": "US",
        "reasons": [
          {
            "name": "wrong_size",
            "value": "Wrong Size",
            "reasons": {
              "name": "to_small",
              "value": "Too Small"
            }
          }
        ]
      }
    ],
    "return_method": {
      "id": "f936964c2a7745dc8e0f2d055efabd50",
      "carrier": "fedex",
      "carrier_logo": "https://test-cdn.zenkraft.com/static/images/carriers/fedex.png",
      "carrier_name": "FedEx",
      "method_name": "FedEx Drop Off",
      "type": "drop_off",
      "cost": {
        "carrier_charge": 4.99,
        "customer_charge": 4.99
      },
      "return_charge": 4.99
    },
    "pickup": {
      "id": "7acd186c4bad4197ad36b918eff71c03",
      "confirmation_number": "123456789",
      "reference_number": "567293923024"
    },
    "shipment": {
      "id": "string",
      "tracking_number": "567293923024",
      "reference_number": "567293923024",
      "status": "Delivered to a mailbox",
      "label": "string"
    }
  }
]

/return_methods POST

These endpoints allow you to handle shipment return methods.

The following example includes all of the request parameters that Zenkraft supports. To see the required and optional parameters for a specific carrier, select from the Choose Carrier dropdown in the menu.

POST Request Parameters
Field Possible Values Example
return_method object required
display_name string required Free Returns
filters array required
field string return_from_country
operator string not_equals not_in in equals
value string HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
location_id string required ed813903af74445398e59aec69a955ff
method_name string required DHL Ground Services
position integer Return method position, it must be more than -1. required 0
return_charge string required 10.05
service_type string required FedEx 2 Day
sf_shipping_preference_id string ed813903af74445398e59aec69a955ff
shipping_account_id integer required 123
type string required drop_off pickup drop_off


Successful Response
Field Possible Values Example
return_method object
display_name string required Free Returns
filters array required
field string return_from_country
operator string not_equals in equals not_in
value string HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
id string required
location_id string required ed813903af74445398e59aec69a955ff
method_name string required DHL Ground Services
position integer Return method position, it must be more than -1. required
return_charge string required 10.05
service_type string required FedEx 2 Day
sf_shipping_preference_id string ed813903af74445398e59aec69a955ff
shipping_account_id integer required 123
type string required pickup drop_off drop_off


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required Missing zkkey HTTP header containing your Zenkraft API key
Example Request / Response
{
  "return_method": {
    "position": 0,
    "method_name": "DHL Ground Services",
    "display_name": "Free Returns",
    "type": "drop_off",
    "shipping_account_id": 123,
    "location_id": "ed813903af74445398e59aec69a955ff",
    "service_type": "FedEx 2 Day",
    "return_charge": "10.05",
    "filters": [
      {
        "field": "return_from_country",
        "operator": "equals",
        "value": "US"
      },
      {
        "field": "total_value",
        "operator": "equals",
        "value": "50"
      }
    ]
  }
}
                curl --request POST \
--url https://api.zenkraft.com/return/methods \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
  "return_method": {
    "position": 0,
    "method_name": "DHL Ground Services",
    "display_name": "Free Returns",
    "type": "drop_off",
    "shipping_account_id": 123,
    "location_id": "ed813903af74445398e59aec69a955ff",
    "service_type": "FedEx 2 Day",
    "return_charge": "10.05",
    "filters": [
      {
        "field": "return_from_country",
        "operator": "equals",
        "value": "US"
      },
      {
        "field": "total_value",
        "operator": "equals",
        "value": "50"
      }
    ]
  }
}'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = {
  "return_method": {
    "position": 0,
    "method_name": "DHL Ground Services",
    "display_name": "Free Returns",
    "type": "drop_off",
    "shipping_account_id": 123,
    "location_id": "ed813903af74445398e59aec69a955ff",
    "service_type": "FedEx 2 Day",
    "return_charge": "10.05",
    "filters": [
      {
        "field": "return_from_country",
        "operator": "equals",
        "value": "US"
      },
      {
        "field": "total_value",
        "operator": "equals",
        "value": "50"
      }
    ]
  }
}
url = "https://api.zenkraft.com/return/methods"

response = requests.request(url=url, method='POST', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "return_method": {
    "position": 0,
    "method_name": "DHL Ground Services",
    "display_name": "Free Returns",
    "type": "drop_off",
    "shipping_account_id": 123,
    "location_id": "ed813903af74445398e59aec69a955ff",
    "service_type": "FedEx 2 Day",
    "return_charge": "10.05",
    "filters": [
      {
        "field": "return_from_country",
        "operator": "equals",
        "value": "US"
      },
      {
        "field": "total_value",
        "operator": "equals",
        "value": "50"
      }
    ],
    "id": "string"
  }
}


/return_methods GET

This endpoint allows you to retrieve previously created return methods.

Successful Response
Field Possible Values Example
return_methods array
display_name string Free Returns
filters array
field string return_from_country
operator string not_equals in equals not_in
value string HK GM KW NE MF KP BA BR CM UZ GY BJ PK BI ZA LB BN GG TV HU EG AD DK ST CL IS TK SS DM RU SJ SH KE IR SV MZ AT GS HM KM LU FK MY BT HR CA AX GI PG GT HT TN TZ MP VC DJ AS CZ VG QA BB VI NZ SN ME MW SE LC EE PA AL EH BG MG LI LS KZ CG SY TT BQ CD IM MA CR NR UM MS PH TM SR FM SG AZ BZ PE RO TO ET TL TR SA UG CY IL LT MH BD SL YE WS AI BV SB DZ AR JE MR BO KY SD MX NA AG KN PF CN LK RS IT VN PT MU ES AM ML GD GL IE IN MK CF TC BY CH GE JO JP FI KI NP DE AU NC PL GW MD MO AQ US WF ZM ZW GQ IQ LY UA GP GA KR NO ER EC HN LA MN CI BW FJ NL SM CV FR MV PY CO GF VU MM MT CC PN BL SC IO VA UY LV NU KG CX GB TH KH GR AF AW PR TJ GH JM BM LR BS VE AE BF NG PS AO RW CW TF NI RE FO YT PM SX NF CK GU SK TW TG BH SZ MC SO DO TD BE OM SI GN MQ CU PW ID US
id string
location_id string ed813903af74445398e59aec69a955ff
method_name string DHL Ground Services
position integer Return method position, it must be more than -1.
return_charge string 10.05
service_type string FedEx 2 Day
sf_shipping_preference_id string ed813903af74445398e59aec69a955ff
shipping_account_id integer 123
type string pickup drop_off drop_off


Error Response
Field Possible Values Example
error object
code string Standardized error code required missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception
detail string This field can contain additional information about the error. This field is not meant to be shown to the end-user required
message string Error message required Missing zkkey HTTP header containing your Zenkraft API key
Example Request / Response
https://api.zenkraft.com/return_methods
                curl --request GET \
--url https://api.zenkraft.com/return_methods \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX'
            

import requests

headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}

payload = None
url = "https://api.zenkraft.com/return_methods"

response = requests.request(url=url, method='GET', json=payload, headers=headers)

print(response.json())
            
                
            
{
  "return_methods": [
    {
      "position": 0,
      "method_name": "DHL Ground Services",
      "display_name": "Free Returns",
      "type": "drop_off",
      "shipping_account_id": 123,
      "location_id": "ed813903af74445398e59aec69a955ff",
      "service_type": "FedEx 2 Day",
      "return_charge": "10.05",
      "filters": [
        {
          "field": "return_from_country",
          "operator": "equals",
          "value": "US"
        },
        {
          "field": "total_value",
          "operator": "equals",
          "value": "50"
        }
      ],
      "id": "string"
    }
  ]
}

Object References

currencies

Field Type Required Min Length Max Length

locale

requested locale

Field Type Required Min Length Max Length

countries

Field Type Required Min Length Max Length

location

Field Type Required Min Length Max Length
name string True - 35
company string - 35
street1 string True - 35
street2 string - 35
street3 string - 35
email string - -
phone string 10 15
city string True - 35
state string - 35
postal_code string - 20
country string True - -

packages

We need to know the size and dimensions of your packages.

Field Type Required Min Length Max Length
weight number True - -
value number - -
length number - -
width number - -
height number - -

references

For carriers that allow you to add reference information to your shipment.

Field Type Required Min Length Max Length
type string True - -
value string True - -

tracking_number

Tracking number of shipment

Field Type Required Min Length Max Length

reference_number

some carriers allow you to track either by the tracking number or the reference number

Field Type Required Min Length Max Length

confirmation_number

reference number of this pickup. It can be used to cancel the pickup if the carrier allows it

Field Type Required Min Length Max Length

shipping_account

Shipping account number

Field Type Required Min Length Max Length

special_services

Specific special services (e.g. COD or a Required Signature) depend on a carrier, so go through our documentation to find which those are

Field Type Required Min Length Max Length

notifications

For carriers that allow you to set email/sms for notifications to your shippers.

Field Type Required Min Length Max Length
type string True - -
value string True - -

customs_items

Additional information about packages

Field Type Required Min Length Max Length
description string True - -
quantity integer True - -
value number True - -
weight number True - -

costs

Additional information about packages

Field Type Required Min Length Max Length
base_charge number - -
net_charge number - -
taxes number - -
surcharges number - -
discounts number - -

shipping_documents

Additional information about packages

Field Type Required Min Length Max Length
description string True - -
document_type string True - -
document string True - -

carrier

the carrier name

Field Type Required Min Length Max Length

status

the most recent important status description

Field Type Required Min Length Max Length

tracking_stage

the most recent important status standardized shipment stage

Field Type Required Min Length Max Length

label_type

the label format of the shipping labels

Field Type Required Min Length Max Length

label_size

the shipping labels size

Field Type Required Min Length Max Length

service

the service type

Field Type Required Min Length Max Length

recipient

Recipient of shiment

Field Type Required Min Length Max Length
name string True - 35
company string - 35
street1 string True - 35
street2 string - 35
street3 string - 35
email string - -
phone string 10 15
city string True - 35
state string - 35
postal_code string - 20
country string True - -

dim_units

Dimension units of the packages, inches or centimeters

Field Type Required Min Length Max Length

weight_units

Weight units of the packages, pounds or kilograms

Field Type Required Min Length Max Length

created

when was this object created

Field Type Required Min Length Max Length

updated

when was this object updated

Field Type Required Min Length Max Length

debug

calls with debug=true will be logged

Field Type Required Min Length Max Length

base_shipment

Definition of the shipment payload

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
ship_date string - -
type string - -
service string - -
special_services array - -
packaging string True - -
dim_units string True - -
weight_units string True - -
currency string - -
sender object True - -
recipient object True - -
packages array True - -

shipment

Definition of the shipment payload

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
ship_date string - -
type string - -
service string True - -
special_services array - -
packaging string True - -
dim_units string True - -
weight_units string True - -
currency string - -
sender object True - -
recipient object True - -
packages array True - -
label_type string True - -
label_size string - -
include_base64_label boolean - -
references array - -
notifications array - -

shipment_id

shipment ID

Field Type Required Min Length Max Length

shipment_status

Standardized shipment status

Field Type Required Min Length Max Length

ship_response

Field Type Required Min Length Max Length
shipment True - -

_shipment_status_response

Field Type Required Min Length Max Length
shipment True - -

shipment_status_pending_response

Field Type Required Min Length Max Length
shipment True - -

shipment_status_success_response

Field Type Required Min Length Max Length
shipment True - -

rate

Definition of the shipment payload

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
ship_date string - -
type string - -
service string - -
special_services array - -
packaging string True - -
dim_units string True - -
weight_units string True - -
currency string - -
sender object True - -
recipient object True - -
packages array True - -

rate_response

Field Type Required Min Length Max Length
rates array True - -

pickup_response

Field Type Required Min Length Max Length
pickup object True - -

cancel_pickup_response

Field Type Required Min Length Max Length
cancel object True - -

pickup_availability_response

Field Type Required Min Length Max Length
pickup_availability object True - -

cancel_pickup

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
confirmation_number string True - -

_pickup

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
description string - -
currency string - -
dim_units string True - -
weight_units string True - -
location object True - -
shipments array True - -
time object True - -

__pickup

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
description string - -
currency string - -
dim_units string True - -
weight_units string True - -
location object True - -
shipments array True - -

__track

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
checkpoints boolean - -
refresh boolean - -
webhooks boolean - -
locale string - -

track_by_tracking_number

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
checkpoints boolean - -
refresh boolean - -
webhooks boolean - -
locale string - -
tracking_number string True - -

track_by_reference_number

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
checkpoints boolean - -
refresh boolean - -
webhooks boolean - -
locale string - -
reference_number string True - -

track

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
checkpoints boolean - -
refresh boolean - -
webhooks boolean - -
locale string - -
tracking_number string True - -

estimated_delivery

estimated delivery date of this shipment

Field Type Required Min Length Max Length

track_response

Field Type Required Min Length Max Length
carrier string - -
delivered boolean - -
estimated_delivery string - -
delivery_date string - -
tracking_number string - -
status string - -
tracking_stage string - -
locale string - -
checkpoints array - -

manifest_id

carrier ID of this manifest which can be used in GET on /manifest/<manifest_id>

Field Type Required Min Length Max Length

manifest_post_response

Field Type Required Min Length Max Length
manifest True - -

manifest_get_response

Field Type Required Min Length Max Length
manifest True - -

manifest_list_response

Field Type Required Min Length Max Length
manifests array True - -

webhook

Field Type Required Min Length Max Length
name string - -
description string - -
debug boolean - -
api_version string - -
format string - -
events array - -
callback string True - -
headers array - -
shipping_account_id integer - -
trigger_mode string - -

webhook_list_response

Field Type Required Min Length Max Length
webhooks array True - -

webhook_id

ID of the subscription

Field Type Required Min Length Max Length

_webhook_response

Field Type Required Min Length Max Length
name string - -
description string - -
debug boolean - -
api_version string - -
format string - -
events array - -
callback string True - -
headers array - -
shipping_account_id integer - -
trigger_mode string - -
id string - -

webhook_response

Field Type Required Min Length Max Length
webhook object - -

dopu

Field Type Required Min Length Max Length
carrier string True - -
shipping_account string True - -
test boolean - -
debug boolean - -
location object True - -

dopu_response

Field Type Required Min Length Max Length
locations array True - -

shippingaccount_response

Carrier credentials

Field Type Required Min Length Max Length
shipping_account object True - -

error

Field Type Required Min Length Max Length
error object True - -

ship_error

Field Type Required Min Length Max Length
error object True - -

shipment_status_error

Field Type Required Min Length Max Length
error object True - -

rate_error

Field Type Required Min Length Max Length
error object True - -

shippingaccount_error

Field Type Required Min Length Max Length
error object True - -

track_error

Field Type Required Min Length Max Length
error object True - -

dopu_error

Field Type Required Min Length Max Length
error object True - -

pickup_error

Field Type Required Min Length Max Length
error object True - -

pickup_availability_error

Field Type Required Min Length Max Length
error object True - -

manifest_error

Field Type Required Min Length Max Length
error object True - -

webhook_error

Field Type Required Min Length Max Length
error object True - -

location_error

Field Type Required Min Length Max Length
error object True - -

successful_response

Field Type Required Min Length Max Length