API Docs
Customers need to quickly change and add carriers without incurring costly and
restrictive technical debt. Every carrier has different integration methods, requiring
a new development project for every new or updated carrier. This workload compounds as
you expand globally and work with a larger number of carriers.
The Zenkraft API integrates directly with shipping carriers such as
FedEx, UPS, and
DHL through a single platform. Integrate with Zenkraft’s
developer-friendly API and let Zenkraft handle the complexities of global carrier
integration.
This page includes examples of the Zenkraft API’s structure and parameters. Select a
carrier from the dropdown list in the navigation menu to access API reference
documentation listing their required and accepted parameters.
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_keyBase 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 | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
US |
| defaults object | |
|
| currency string | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT MNT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP GNF |
|
| 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 |
|
| parent_shipping_account string Shipping account key to link this account to. This is useful when you want to create a sub-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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
US |
| defaults object required | |
|
| currency string | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT MNT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP GNF |
|
| 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 |
|
| parent_shipping_account string Shipping account key to link this account to. This is useful when you want to create a sub-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 | master_test_shipping_account_not_found schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key wrong_api_key schema_validation_error 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())
/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 | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT MNT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP GNF |
|
| 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 required | |
|
| city string the city of the recipient | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient | 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 | 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 required | |
|
| city string the city of the recipient | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient | 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 | 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 | return outbound |
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_timeout carrier_failed_connection carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method unexpected_exception ship_date_past |
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": "2026-01-15",
"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": "2026-01-15",
"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": "2026-01-15",
"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())
/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 |
|
| combined_labels boolean Optional flag indicating whether package labels should be combined | |
|
| currency string | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT MNT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP GNF |
|
| 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 | PNG ZPL GIF PDF JPG |
PDF |
| notifications array | |
|
| type string type of the notification needed | sms email |
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 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | return outbound |
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_numberwhich can be used to track the shipments in the track endpointlabelfor 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_timeout carrier_failed_connection carrier_label_generation_failed carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key carrier_shipment_generation_failed invalid_phone_number schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method unexpected_exception ship_date_past |
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": "2026-01-15",
"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": "2026-01-15",
"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": "2026-01-15",
"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": "2026-01-15",
"type": "outbound",
"combined_labels": false,
"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 | PNG ZPL GIF PDF JPG |
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_timeout carrier_failed_connection carrier_no_shipment_found carrier_label_generation_failed carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method 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 | 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": "2026-01-15",
"type": "outbound",
"combined_labels": false,
"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 | tzm_Latn_MA ff_SN ii_CN ur_IN shi_Latn uk_UA ar_SY bs_BA gsw_CH ar_TN sw_KE pa_Guru_IN kk_Cyrl ha_Latn_NG fr_RE it_CH en_IN rw_RW sk_SK be_BY pt_BR ro_RO id_ID fr_MQ so_ET teo_KE ru_RU uz_Arab mg_MG kn_IN az_Latn ha_Latn_GH yo_NG am_ET th_TH bem_ZM rof_TZ sr_Cyrl_BA fr_BI en_TT et_EE pa_Arab_PK zh_Hant_TW ga_IE fr_TG zh_Hans_MO kam_KE az_Cyrl_AZ en_ZA es_HN fr_BL ro_MD lg_UG fr_ML ru_UA es_CL sv_SE az_Cyrl en_UM sl_SI fr_CD uz_Latn bo_IN nn_NO ses_ML luo_KE es_CO fr_GA ar_JO sv_FI es_PA sr_Latn_BA ha_Latn_NE fr_CI ee_TG fr_NE ar_EG en_MU en_NA en_MP fr_CA fr_SN sw_TZ ha_Latn en_HK ar_OM sn_ZW ar_SA om_ET tzm_Latn ar_AE ka_GE kea_CV fr_CF uz_Cyrl_UZ sr_Latn uz_Arab_AF ne_IN guz_KE saq_KE ar_MA asa_TZ de_LI ta_IN kw_GB ar_QA kl_GL hu_HU si_LK om_KE sg_CF en_BE es_PE te_IN es_AR fr_CM cgg_UG lt_LT en_GU fr_GQ de_BE sr_Cyrl shi_Latn_MA nd_ZW so_SO cy_GB chr_US en_US fr_MG fr_GP es_CR es_PY ar_DZ fr_CG to_TO fr_BJ es_EC so_DJ fa_AF vi_VN fr_FR de_CH hy_AM en_VI es_NI naq_NA hr_HR ur_PK zh_Hans_HK en_JM bez_TZ khq_ML shi_Tfng_MA fr_KM kde_TZ shi_Tfng en_SG ko_KR hi_IN gl_ES es_ES en_MT de_LU zh_Hant pa_Guru fr_MF so_KE fr_DJ kln_KE ebu_KE zh_Hant_HK my_MM rwk_TZ ar_LY es_UY tr_TR ar_KW da_DK ig_NG ne_NP gu_IN ms_MY fa_IR el_CY mfe_MU ar_SD pt_PT ps_AF mk_MK az_Latn_AZ fr_LU fr_MC zh_Hans ml_IN es_419 ta_LK fr_BF es_GT nl_NL es_SV lag_TZ vun_TZ ak_GH sr_Latn_RS fil_PH ja_JP es_GQ en_IL kk_Cyrl_KZ nb_NO ki_KE ti_ER es_VE es_MX es_US he_IL bo_CN cs_CZ kok_IN fr_RW en_CA sr_Cyrl_ME es_BO dav_KE bn_IN it_IT en_NZ ru_MD en_PH en_AU en_IE jmc_TZ fo_FO af_ZA nyn_UG zh_Hans_SG es_DO mas_TZ sr_Latn_ME en_GB en_PK de_AT fi_FI pa_Arab km_KH gv_GB or_IN luy_KE ar_BH en_AS as_IN uz_Latn_UZ ar_IQ kab_DZ teo_UG en_BW bm_ML mt_MT pt_GW rm_CH ar_YE yue_Hant_HK en_ZW de_DE sr_Cyrl_RS xog_UG es_PR ar_LB ms_BN zu_ZA uz_Cyrl zh_Hant_MO mr_IN bg_BG fr_TD en_MH mas_KE nl_BE zh_Hans_CN sq_AL mer_KE is_IS haw_US seh_MZ fr_GN ca_ES ti_ET en_BZ pt_MZ el_GR ee_GH fr_CH af_NA eu_ES bn_BD lv_LV pl_PL fr_BE |
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 | CREATION_PENDING CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DRIVER_ASSIGNED CHECKED_IN 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 | tzm_Latn_MA ff_SN ii_CN ur_IN shi_Latn uk_UA ar_SY bs_BA gsw_CH ar_TN sw_KE pa_Guru_IN kk_Cyrl ha_Latn_NG fr_RE it_CH en_IN rw_RW sk_SK be_BY pt_BR ro_RO id_ID fr_MQ so_ET teo_KE ru_RU uz_Arab mg_MG kn_IN az_Latn ha_Latn_GH yo_NG am_ET th_TH bem_ZM rof_TZ sr_Cyrl_BA fr_BI en_TT et_EE pa_Arab_PK zh_Hant_TW ga_IE fr_TG zh_Hans_MO kam_KE az_Cyrl_AZ en_ZA es_HN fr_BL ro_MD lg_UG fr_ML ru_UA es_CL sv_SE az_Cyrl en_UM sl_SI fr_CD uz_Latn bo_IN nn_NO ses_ML luo_KE es_CO fr_GA ar_JO sv_FI es_PA sr_Latn_BA ha_Latn_NE fr_CI ee_TG fr_NE ar_EG en_MU en_NA en_MP fr_CA fr_SN sw_TZ ha_Latn en_HK ar_OM sn_ZW ar_SA om_ET tzm_Latn ar_AE ka_GE kea_CV fr_CF uz_Cyrl_UZ sr_Latn uz_Arab_AF ne_IN guz_KE saq_KE ar_MA asa_TZ de_LI ta_IN kw_GB ar_QA kl_GL hu_HU si_LK om_KE sg_CF en_BE es_PE te_IN es_AR fr_CM cgg_UG lt_LT en_GU fr_GQ de_BE sr_Cyrl shi_Latn_MA nd_ZW so_SO cy_GB chr_US en_US fr_MG fr_GP es_CR es_PY ar_DZ fr_CG to_TO fr_BJ es_EC so_DJ fa_AF vi_VN fr_FR de_CH hy_AM en_VI es_NI naq_NA hr_HR ur_PK zh_Hans_HK en_JM bez_TZ khq_ML shi_Tfng_MA fr_KM kde_TZ shi_Tfng en_SG ko_KR hi_IN gl_ES es_ES en_MT de_LU zh_Hant pa_Guru fr_MF so_KE fr_DJ kln_KE ebu_KE zh_Hant_HK my_MM rwk_TZ ar_LY es_UY tr_TR ar_KW da_DK ig_NG ne_NP gu_IN ms_MY fa_IR el_CY mfe_MU ar_SD pt_PT ps_AF mk_MK az_Latn_AZ fr_LU fr_MC zh_Hans ml_IN es_419 ta_LK fr_BF es_GT nl_NL es_SV lag_TZ vun_TZ ak_GH sr_Latn_RS fil_PH ja_JP es_GQ en_IL kk_Cyrl_KZ nb_NO ki_KE ti_ER es_VE es_MX es_US he_IL bo_CN cs_CZ kok_IN fr_RW en_CA sr_Cyrl_ME es_BO dav_KE bn_IN it_IT en_NZ ru_MD en_PH en_AU en_IE jmc_TZ fo_FO af_ZA nyn_UG zh_Hans_SG es_DO mas_TZ sr_Latn_ME en_GB en_PK de_AT fi_FI pa_Arab km_KH gv_GB or_IN luy_KE ar_BH en_AS as_IN uz_Latn_UZ ar_IQ kab_DZ teo_UG en_BW bm_ML mt_MT pt_GW rm_CH ar_YE yue_Hant_HK en_ZW de_DE sr_Cyrl_RS xog_UG es_PR ar_LB ms_BN zu_ZA uz_Cyrl zh_Hant_MO mr_IN bg_BG fr_TD en_MH mas_KE nl_BE zh_Hans_CN sq_AL mer_KE is_IS haw_US seh_MZ fr_GN ca_ES ti_ET en_BZ pt_MZ el_GR ee_GH fr_CH af_NA eu_ES bn_BD lv_LV pl_PL fr_BE |
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 | CREATION_PENDING CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DRIVER_ASSIGNED CHECKED_IN DELIVERED SHIPMENT_VOIDED EXCEPTION |
DELIVERED |
Error Response
| Field | Possible Values | Example |
|---|---|---|
| error object | |
|
| code string Standardized error code required | carrier_timeout carrier_failed_connection carrier_no_shipment_found carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method 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 | tzm_Latn_MA ff_SN ii_CN ur_IN shi_Latn uk_UA ar_SY bs_BA gsw_CH ar_TN sw_KE pa_Guru_IN kk_Cyrl ha_Latn_NG fr_RE it_CH en_IN rw_RW sk_SK be_BY pt_BR ro_RO id_ID fr_MQ so_ET teo_KE ru_RU uz_Arab mg_MG kn_IN az_Latn ha_Latn_GH am_ET th_TH bem_ZM rof_TZ sr_Cyrl_BA fr_BI fr_BE en_TT et_EE pa_Arab_PK zh_Hant_TW ga_IE fr_TG zh_Hans_MO kam_KE az_Cyrl_AZ en_ZA es_HN fr_BL ro_MD lg_UG fr_ML ru_UA es_CL sv_SE az_Cyrl en_UM sl_SI fr_CD uz_Latn bo_IN nn_NO ses_ML luo_KE es_CO fr_GA ar_JO sv_FI es_PA sr_Latn_BA ha_Latn_NE fr_CI ee_TG fr_NE ar_EG en_MU en_NA en_MP fr_CA fr_SN sw_TZ ha_Latn en_HK ar_OM sn_ZW ar_SA om_ET tzm_Latn ar_AE ka_GE kea_CV fr_CF uz_Cyrl_UZ sr_Latn uz_Arab_AF ne_IN guz_KE saq_KE ar_MA asa_TZ de_LI ta_IN kw_GB ar_QA kl_GL hu_HU si_LK om_KE sg_CF en_BE es_PE te_IN es_AR fr_CM cgg_UG lt_LT en_GU fr_GQ de_BE sr_Cyrl shi_Latn_MA nd_ZW so_SO cy_GB chr_US en_US fr_MG fr_GP es_CR es_PY ar_DZ fr_CG to_TO fr_BJ es_EC so_DJ fa_AF vi_VN fr_FR de_CH hy_AM en_VI es_NI naq_NA hr_HR ur_PK zh_Hans_HK en_JM bez_TZ khq_ML shi_Tfng_MA fr_KM kde_TZ shi_Tfng en_SG ko_KR hi_IN gl_ES es_ES en_MT de_LU zh_Hant pa_Guru fr_MF so_KE fr_DJ kln_KE ebu_KE zh_Hant_HK my_MM rwk_TZ ar_LY es_UY tr_TR ar_KW da_DK ig_NG ne_NP gu_IN ms_MY fa_IR el_CY mfe_MU ar_SD pt_PT ps_AF mk_MK az_Latn_AZ fr_LU fr_MC zh_Hans ml_IN es_419 ta_LK fr_BF es_GT nl_NL es_SV lag_TZ vun_TZ ak_GH sr_Latn_RS fil_PH ja_JP es_GQ en_IL kk_Cyrl_KZ nb_NO ki_KE ti_ER es_VE es_MX es_US he_IL bo_CN cs_CZ kok_IN fr_RW en_CA sr_Cyrl_ME es_BO dav_KE bn_IN it_IT en_NZ ru_MD en_PH en_AU en_IE jmc_TZ fo_FO af_ZA nyn_UG zh_Hans_SG es_DO mas_TZ sr_Latn_ME en_GB en_PK de_AT fi_FI pa_Arab km_KH gv_GB or_IN luy_KE ar_BH en_AS as_IN uz_Latn_UZ ar_IQ kab_DZ teo_UG en_BW bm_ML mt_MT pt_GW rm_CH ar_YE yue_Hant_HK en_ZW de_DE sr_Cyrl_RS xog_UG es_PR ar_LB ms_BN zu_ZA uz_Cyrl zh_Hant_MO mr_IN bg_BG fr_TD en_MH mas_KE nl_BE zh_Hans_CN sq_AL mer_KE is_IS haw_US seh_MZ fr_GN ca_ES ti_ET en_BZ pt_MZ el_GR ee_GH fr_CH af_NA eu_ES bn_BD lv_LV pl_PL yo_NG |
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_timeout carrier_failed_connection carrier_no_shipment_found carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method 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())
/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 | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD GNF MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP MNT |
|
| 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 | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | |
|
| 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | carrier_timeout carrier_failed_connection carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key invalid_phone_number schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method unexpected_exception ship_date_past |
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": "2026-01-15",
"end_date": "2026-01-15"
}
}
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": "2026-01-15",
"end_date": "2026-01-15"
}
}'
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": "2026-01-15",
"end_date": "2026-01-15"
}
}
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": "2026-01-15",
"end_date": "2026-01-15",
"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 | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT MNT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP GNF |
|
| 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | |
|
| 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 | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | CVE KRW BYN SHP DKK RON PLN XOF LAK CLP MYR BGN ANG GGP XDR AFN IDR ZWD THB ZMW KHR IMP GYD NIO RSD JMD GNF MKD FKP LBP BIF KMF SLL MAD GTQ SCR TMT EGP ARS SVC PHP BOB NGN STN UZS UYU GBP FJD SGD SOS NPR LRD TVD ILS WST BSD TRY HUF BHD OMR TJS CUP HKD MZN PAB AED BWP CUC ERN QAR JPY CRC MMK NZD AZN BDT COP GMD VEF INR ISK KPW CHF MUR EUR BBD TZS XCD AMD VUV GHS BZD SRD KZT ZAR BMD RWF JOD MWK TOP PKR AUD LSL KES VND MXN RUB SYP LYD NOK XPF AOA KWD NAD SBD IRR TTD TND CNY UAH TWD PGK MRU YER IQD CZK ALL ETB SAR MDL SDG KGS LKR DZD DJF MGA CDF PYG PEN AWG SZL BND SPL BAM UGX MVR SEK USD BRL HRK HTG BTN HNL GEL GIP XAF KYD JEP CAD MOP DOP MNT |
|
| 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 | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | |
|
| 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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_timeout carrier_failed_connection carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key invalid_phone_number schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method unexpected_exception ship_date_past |
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 | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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_timeout carrier_failed_connection carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method 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_timeout carrier_failed_connection carrier_authentication schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key carrier_exception wrong_api_key schema_validation_error carrier_throttling carrier_http_exception carrier_unsupported_method 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 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())
/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 | return.shipment_voided shipment.shipment_voided shipment.picked_up shipment.driver_assigned return.creation_pending shipment.exception return.checked_in shipment.delivered shipment.in_transit return.out_for_delivery shipment.created return.delivered return.in_transit return.picked_up return.driver_assigned shipment.creation_pending return.exception shipment.out_for_delivery shipment.checked_in return.created |
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 | return.shipment_voided shipment.shipment_voided shipment.picked_up shipment.driver_assigned return.creation_pending shipment.exception return.checked_in shipment.delivered shipment.in_transit return.out_for_delivery shipment.created return.delivered return.in_transit return.picked_up return.driver_assigned shipment.creation_pending return.exception shipment.out_for_delivery shipment.checked_in return.created |
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 | return.shipment_voided shipment.shipment_voided shipment.picked_up shipment.driver_assigned return.creation_pending shipment.exception return.checked_in shipment.delivered shipment.in_transit return.out_for_delivery shipment.created return.delivered return.in_transit return.picked_up return.driver_assigned shipment.creation_pending return.exception shipment.out_for_delivery shipment.checked_in return.created |
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 | return.shipment_voided shipment.shipment_voided shipment.picked_up shipment.driver_assigned return.creation_pending shipment.exception return.checked_in shipment.delivered shipment.in_transit return.out_for_delivery shipment.created return.delivered return.in_transit return.picked_up return.driver_assigned shipment.creation_pending return.exception shipment.out_for_delivery shipment.checked_in return.created |
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 | return.shipment_voided shipment.shipment_voided shipment.picked_up shipment.driver_assigned return.creation_pending shipment.exception return.checked_in shipment.delivered shipment.in_transit return.out_for_delivery shipment.created return.delivered return.in_transit return.picked_up return.driver_assigned shipment.creation_pending return.exception shipment.out_for_delivery shipment.checked_in return.created |
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 | schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key wrong_api_key schema_validation_error webhook_not_found 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 | schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key wrong_api_key schema_validation_error webhook_not_found 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())
/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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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())
/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 | in not_equals not_in equals |
|
| value string | PA CM SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | in not_equals not_in equals |
|
| value string | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 | in not_equals not_in equals |
|
| value string | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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"
}
]
}/validate_address POST
You can use /validate_address to automatically fix the address before you try to create the label.
The request always validates the address and optionally you can set validate_phone and
validate_email to also validate the phone number and the email respectively.
POST Request Parameters
| Field | Possible Values | Example |
|---|---|---|
| validate object required | |
|
| 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 |
|
| debug boolean | |
|
| validate_email boolean | |
|
| validate_phone boolean | |
Successful Response
| Field | Possible Values | Example |
|---|---|---|
| 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 | CM PA SC OM DE SH KN AZ SN ZA DZ CW IS JE SB SX GI BM PK SE GR MK LS MY TJ HU DO AM SS TZ MD AL MU TK CZ JO LB MF YE PW EH RE RS CY VI LR MR PS GM BE UG GG TD AI LA CO PF VN HN WF SO TV VA KP GW JM MH KY BR NF SG ZM NC NE VC SY KE AW MX NG BD EC AQ WS BT SR KG PL UZ ZW NO AE TC BV BQ IE NP BO CV EE AG BL CG GD GH NL HR CN RW SJ SK MS TR UY ID LU MV GS AD IR MC FM BG GP MO SM TF BN GQ LK CC AR GE GN JP RU SZ CH MA IO PE KZ ER PG BJ BH LV CA GT PN RO LI SL AO MM NA NZ MT GL MN AT VG EG KW IT LY CD SV TG PR VU CF BZ DK TW KM PH GF IN KI BF GA KR GU HT TM CL CX MZ UM PY US TH AS PT AF PM TL LC LT IL HK UA YT CI HM MQ DM TT DJ ES FJ MP NU SI BB NR KH VE TN IQ NI ME FO AU BS GY ET CK MG GB AX BW BY CR FR CU MW QA FK BA TO IM SD ST SA FI BI ML |
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 |
|
| fixed boolean | |
Error Response
| Field | Possible Values | Example |
|---|---|---|
| error object | |
|
| code string Standardized error code. required | schema_field_required shipping_account_not_found shipping_account_wrong_carrier missing_api_key wrong_api_key connected_account_not_found schema_validation_error 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 connected account exists with that ID |
Example Request / Response
{
"validate": {
"debug": true,
"address": {
"city": "West Hollywood",
"company": "Fresh Corn Grill",
"country": "US",
"state": "CA",
"email": "test@test.yesyesghse",
"name": "Dio",
"phone": "+4367764842356",
"postal_code": "1002",
"street1": "8714 Santa Monica Blvd, West Hollywood"
},
"validate_phone": false,
"validate_email": false
}
}
curl --request POST \
--url https://api.zenkraft.com/validate/address \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
"validate": {
"debug": true,
"address": {
"city": "West Hollywood",
"company": "Fresh Corn Grill",
"country": "US",
"state": "CA",
"email": "test@test.yesyesghse",
"name": "Dio",
"phone": "+4367764842356",
"postal_code": "1002",
"street1": "8714 Santa Monica Blvd, West Hollywood"
},
"validate_phone": false,
"validate_email": false
}
}'
import requests
headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}
payload = {
"validate": {
"debug": true,
"address": {
"city": "West Hollywood",
"company": "Fresh Corn Grill",
"country": "US",
"state": "CA",
"email": "test@test.yesyesghse",
"name": "Dio",
"phone": "+4367764842356",
"postal_code": "1002",
"street1": "8714 Santa Monica Blvd, West Hollywood"
},
"validate_phone": false,
"validate_email": false
}
}
url = "https://api.zenkraft.com/validate/address"
response = requests.request(url=url, method='POST', json=payload, headers=headers)
print(response.json())
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_base
| Field | Type | Required | Min Length | Max Length |
| name | string | - | 35 | |
| company | string | - | 35 | |
| street1 | string | - | 50 | |
| street2 | string | - | 50 | |
| street3 | string | - | 50 | |
| string | - | 100 | ||
| phone | string | - | 35 | |
| city | string | - | 50 | |
| state | string | - | 35 | |
| postal_code | string | - | 15 | |
| country | string | - | - |
location
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | 35 |
| company | string | - | 35 | |
| street1 | string | True | - | 50 |
| street2 | string | - | 50 | |
| street3 | string | - | 50 | |
| string | - | 100 | ||
| phone | string | - | 35 | |
| city | string | True | - | 50 |
| state | string | - | 35 | |
| postal_code | string | - | 15 | |
| country | string | True | - | - |
location_rate
| Field | Type | Required | Min Length | Max Length |
| name | string | - | 35 | |
| company | string | - | 35 | |
| street1 | string | - | 50 | |
| street2 | string | - | 50 | |
| street3 | string | - | 50 | |
| string | - | 100 | ||
| phone | string | - | 35 | |
| city | string | - | 50 | |
| state | string | - | 35 | |
| postal_code | string | - | 15 | |
| 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 |
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 | - | - | |
| 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 | - | - | |
| packages | array | True | - | - |
| label_type | string | True | - | - |
| label_size | string | - | - | |
| include_base64_label | boolean | - | - | |
| references | array | - | - | |
| notifications | array | - | - | |
| sender | object | True | - | - |
| recipient | object | True | - | - |
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 | - | - | |
| packages | array | True | - | - |
| sender | object | True | - | - |
| recipient | object | 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 |
| success | object | True | - | - |
UserBase
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | - |
| string | True | - | - |
UserDetails
| Field | Type | Required | Min Length | Max Length |
| total_1_day | integer | True | - | - |
| total_7_days | integer | True | - | - |
| total_28_days | integer | True | - | - |
| api_key | string | True | - | - |
| user_token | string | True | - | - |
| company | string | True | - | - |
| created | string | True | - | - |
| mfa | boolean | True | - | - |
User
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | - |
| string | True | - | - | |
| total_1_day | integer | True | - | - |
| total_7_days | integer | True | - | - |
| total_28_days | integer | True | - | - |
| api_key | string | True | - | - |
| user_token | string | True | - | - |
| company | string | True | - | - |
| created | string | True | - | - |
| mfa | boolean | True | - | - |
log_item
| Field | Type | Required | Min Length | Max Length |
| id | string | - | - | |
| created | string | - | - | |
| status_code | number | - | - | |
| url | string | - | - | |
| ip_address | string | - | - |
LogDetails
| Field | Type | Required | Min Length | Max Length |
| id | string | - | - | |
| created | string | - | - | |
| status_code | number | - | - | |
| url | string | - | - | |
| ip_address | string | - | - | |
| http_method | string | True | - | - |
| user_agent | string | True | - | - |
| content_type | string | True | - | - |
| request | object | True | - | - |
| response | object | True | - | - |
ShipmentCheckpoint
| Field | Type | Required | Min Length | Max Length |
| time | string | True | - | - |
| status | string | True | - | - |
| description | string | True | - | - |
ShipmentItem
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| tracking_number | string | True | - | - |
| reference_number | string | True | - | - |
| carrier | string | True | - | - |
| status | string | True | - | - |
| created | string | True | - | - |
| is_return | boolean | True | - | - |
ShipmentDetails
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| tracking_number | string | True | - | - |
| reference_number | string | True | - | - |
| carrier | string | True | - | - |
| status | string | True | - | - |
| created | string | True | - | - |
| is_return | boolean | True | - | - |
| shipping_account_id | integer | True | - | - |
| updated | string | True | - | - |
| estimated_delivery | string | True | - | - |
| checkpoints | array | True | - | - |
LocationBase
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | 35 |
| company | string | True | - | 35 |
| street1 | string | True | - | 50 |
| street2 | string | - | 50 | |
| street3 | string | - | 50 | |
| string | True | - | 100 | |
| phone | string | True | - | 35 |
| city | string | True | - | 50 |
| state | string | True | - | 35 |
| postal_code | string | True | - | 15 |
| country | string | True | - | - |
| type | string | True | - | - |
| timezone | string | - | - | |
| cutoff_hours | integer | - | - | |
| cutoff_minutes | integer | - | - |
Location
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | 35 |
| company | string | True | - | 35 |
| street1 | string | True | - | 50 |
| street2 | string | - | 50 | |
| street3 | string | - | 50 | |
| string | True | - | 100 | |
| phone | string | True | - | 35 |
| city | string | True | - | 50 |
| state | string | True | - | 35 |
| postal_code | string | True | - | 15 |
| country | string | True | - | - |
| type | string | True | - | - |
| timezone | string | - | - | |
| cutoff_hours | integer | - | - | |
| cutoff_minutes | integer | - | - | |
| id | string | True | - | - |
| updated | string | - | - |
return_method_type
| Field | Type | Required | Min Length | Max Length |
return_line
| Field | Type | Required | Min Length | Max Length |
| quantity | integer | True | - | - |
| value | number | True | - | - |
| weight | number | True | - | - |
| product_name | string | True | - | - |
| line_id | string | True | - | - |
| hs_code | string | True | - | - |
| sku | string | True | - | - |
| country_of_manufacture | string | True | - | - |
| reasons | array | True | - | - |
operational_hours
| Field | Type | Required | Min Length | Max Length |
| open | string | True | - | - |
| close | string | True | - | - |
return_cost
| Field | Type | Required | Min Length | Max Length |
| carrier_charge | number | True | - | - |
| customer_charge | number | True | - | - |
ReturnMethodBase
| Field | Type | Required | Min Length | Max Length |
| position | integer | True | - | - |
| method_name | string | True | 1 | 50 |
| display_name | string | True | 1 | 50 |
| type | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| location_id | string | True | - | - |
| sf_shipping_preference_id | string | - | - | |
| service_type | string | True | - | - |
| return_charge | string | True | - | - |
| filters | array | True | - | - |
ReturnMethodCountryFilter
| Field | Type | Required | Min Length | Max Length |
| field | string | True | - | - |
| operator | string | True | - | - |
| value | string | True | - | - |
ReturnMethodNumberFilter
| Field | Type | Required | Min Length | Max Length |
| field | string | True | - | - |
| operator | string | True | - | - |
| value | string | True | - | - |
ReturnMethodCustomFilter
| Field | Type | Required | Min Length | Max Length |
| field | string | True | - | - |
| operator | string | True | - | - |
| name | string | True | - | 50 |
| value | string | True | - | - |
ReturnMethod
| Field | Type | Required | Min Length | Max Length |
| position | integer | True | - | - |
| method_name | string | True | 1 | 50 |
| display_name | string | True | 1 | 50 |
| type | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| location_id | string | True | - | - |
| sf_shipping_preference_id | string | - | - | |
| service_type | string | True | - | - |
| return_charge | string | True | - | - |
| filters | array | True | - | - |
| id | string | True | - | - |
ReturnMethodShortDetails
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| carrier | string | True | - | - |
| carrier_logo | string | True | - | - |
| carrier_name | string | True | - | - |
| method_name | string | True | - | - |
| type | string | True | - | - |
return_pickup
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| confirmation_number | string | True | - | - |
| reference_number | string | True | - | - |
return_shipment
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| tracking_number | string | True | - | - |
| reference_number | string | True | - | - |
| status | string | True | - | - |
| label | string | True | - | - |
ReturnItem
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| customer_id | string | True | - | - |
| order_id | string | - | - | |
| created | string | True | - | - |
| return_lines | array | True | - | - |
| return_method | object | True | - | - |
| pickup | object | - | - | |
| shipment | object | True | - | - |
| custom | array | - | - |
return_method_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
ShipmentEvent
| Field | Type | Required | Min Length | Max Length |
| carrier | string | True | - | - |
| tracking_number | string | True | - | - |
| from_country | string | True | - | - |
| to_country | string | True | - | - |
| service | string | True | - | - |
| is_outbound | boolean | True | - | - |
| total_costs | number | True | - | - |
| currency | string | True | - | - |
| created | string | True | - | - |
FtpConnectedAccountCredentials
| Field | Type | Required | Min Length | Max Length |
| ftp_username | string | True | - | - |
| ftp_password | string | True | - | - |
FtpConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| ftp_username | string | True | - | - |
| ftp_password | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
QuantumViewConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| shipping_account_id | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
ShopifyConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| shop_url | string | True | - | - |
| shipping_account | array | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
custom_context
Custom context attached to the return
| Field | Type | Required | Min Length | Max Length |
NewstoreConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| shipping_account_id | string | True | - | - |
| shipping_account_key | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
SalesforceCore
| Field | Type | Required | Min Length | Max Length |
| service | integer | True | - | - |
| environment | string | True | - | - |
| custom_domain | string | True | - | - |
| client_id | string | - | - | |
| client_secret | string | - | - |
SalesforceCommerceCloud
| Field | Type | Required | Min Length | Max Length |
| url | string | True | - | - |
| service | integer | True | - | - |
ConnectedAccountBase
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| status | string | True | - | - |
ItemConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| status | string | True | - | - |
| ftp_username | string | True | - | - |
| ftp_password | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
CreateConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| status | string | True | - | - |
| ftp_username | string | True | - | - |
| ftp_password | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
UpdateConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| id | string | True | - | - |
| status | string | True | - | - |
| ftp_username | string | True | - | - |
| ftp_password | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
connected_account_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |