Zenkraft API Docs
E-commerce merchants are increasingly using more carriers to provide better delivery and return
options to their customers. Every carrier has
different a different
way to integrate which means
a new development project every time you change or add a carrier. The workload compounds as you
expand globally.
The Zenkraft API is a common interface for interacting with shipping carriers such as
FedEx, UPS and DHL.
Integrate with a developer-friendly API once, and let Zenkraft handle the complexities
of global carrer integration.
UPS Overview
Please find the documentation for the UPS below.
Supported Methods
Ship ✔ Rate ✔ Track ✔ Cancel ✔ Pickup ✔ Dopu ✔ Pickup_Availability ✔ Webhook ✔
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
| Name | API value | Type | Required |
|---|---|---|---|
| User ID | userid | text | True |
| Password | password | text | True |
| Account Number | account_number | text | True |
| Access License Number | access_license_number | text | False |
/ship POST
The shipping endpoint is used to book shipments with UPS. It will return a shipping label and tracking number in the response.
POST Request Parameters
| Field | Possible Values | Example |
|---|---|---|
| shipment object Definition of the shipment payload required | |
|
| carrier string the carrier name required | fedex |
|
| 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
IN |
| include_base64_label boolean If this is enabled, base64 label is returned | |
|
| label_type string the label format of the shipping labels required | EPL ZPL SPL GIF PDF |
PDF |
| notifications array | |
|
| type string type of the notification needed | email sms |
email |
| value string value of the notification | notification1@example.com |
|
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height | 11 |
|
| value number value of the package according to currency specified | 25 |
|
| weight number weight of the package according to units specified under weight_units | 4.2 |
|
| width number width of the package according to units specified under dim_units | 8.5 |
|
| packaging string the packaging type required | your_packaging |
your_packaging |
| recipient object Recipient of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| references array | |
|
| type string type of reference | customer_reference |
|
| value string value of the reference | ABC-000123 |
|
| sender object Sender of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string the service type required | ups_next_day_air |
|
| ship_date string shipping date required | 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 required | outbound return |
outbound |
| weight_units string Weight units of the packages, pounds or kilograms required | KG LB |
LB |
Successful Response
Most important parts of the response:tracking_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 Definition of the shipment payload | |
|
| carrier string the carrier name required | fedex |
|
| 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 |
|
| 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
IN |
| id string shipment ID | 1f02d12868a54ed88b6cb4dafaad325d |
|
| include_base64_label boolean If this is enabled, base64 label is returned | |
|
| label_type string the label format of the shipping labels required | PDF GIF JPG PNG ZPL |
PDF |
| notifications array | |
|
| type string type of the notification needed | email sms |
email |
| value string value of the notification | notification1@example.com |
|
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| 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 |
|
| packaging string the packaging type required | your_packaging |
your_packaging |
| recipient object Recipient of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| references array | |
|
| type string type of reference | customer_reference |
|
| value string value of the reference | ABC-000123 |
|
| sender object Sender of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string the service type required | ups_next_day_air |
|
| ship_date string shipping date required | 2021-06-07 |
|
| shipping_account string Shipping account number required | 5190163571408896 |
|
| 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 |
|
| special_services array | [saturday_delivery ] |
|
| test boolean calls created with test = true will be directed to the carrier test servers | |
|
| tracking_number string Tracking number of shipment | 567293923024 |
|
| type string outbound or return shipments required | outbound return |
outbound |
| 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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection carrier_label_generation_failed carrier_shipment_generation_failed ship_date_past invalid_phone_number |
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. |
Service Types
| Name | API value | Domestic / international |
|---|---|---|
| UPS Next Day Air | ups_next_day_air ➞ | |
| UPS Second Day Air | ups_second_day_air ➞ | |
| UPS Ground | ups_ground ➞ | |
| UPS Express | ups_express ➞ | |
| UPS Expedited | ups_expedited ➞ | |
| UPS Standard | ups_standard ➞ | |
| UPS Three Day Select | ups_three_day_select ➞ | |
| UPS Next Day Air Saver | ups_next_day_air_saver ➞ | |
| UPS Next Day Air Early | ups_next_day_air_early ➞ | |
| UPS Express Plus | ups_express_plus ➞ | |
| UPS 2nd Day Air A.M. | ups_second_day_air_am ➞ | |
| UPS Saver | ups_saver ➞ | |
| UPS Access PointTM Economy | ups_access_point_economy ➞ | |
| UPS First Class Mail | ups_first_class_mail ➞ | |
| UPS Priority Mail | ups_priority_mail ➞ | |
| UPS Expedited MaiI Innovations | ups_expedited_mail_innovations ➞ | |
| UPS Priority Mail Innovations | ups_priority_mail_innovations ➞ | |
| UPS Economy Mail Innovations | ups_economy_mail_innovations ➞ | |
| UPS Today Standard | ups_today_standard ➞ | |
| UPS Today Dedicated Courier | ups_today_dedicated_courier ➞ | |
| UPS Today Intercity | ups_today_intercity ➞ | |
| UPS Today Express | ups_today_express ➞ | |
| UPS Today Express Saver | ups_today_express_saver ➞ | |
| UPS Worldwide Express Freight | ups_worldwide_express_freight ➞ | |
| UPS SurePost Less than 1LB | ups_surepost_lt_1lb ➞ | |
| UPS SurePost | ups_surepost ➞ | |
| UPS Worldwide Economy DDU | ups_worldwide_economy_ddu ➞ | international |
| UPS Worldwide Economy DDP | ups_worldwide_economy_ddp ➞ | international |
| Show more | ||
Packaging Types
| Name | API value | Domestic / international |
|---|---|---|
| Your Packaging | your_packaging ➞ | |
| UPS Letter | ups_letter ➞ | |
| Tube | tube ➞ | |
| PAK | pak ➞ | |
| UPS Express Box | ups_express_box ➞ | |
| UPS 25KG Box | ups_25kg_box ➞ | |
| UPS 10KG Box | ups_10kg_box ➞ | |
| Pallet | pallet ➞ | |
| Small Express Box | small_express_box ➞ | |
| Medium Express Box | medium_express_box ➞ | |
| Large Express Box | large_express_box ➞ | |
| Flats | flats ➞ | |
| Parcels | parcels ➞ | |
| BPM | bpm ➞ | |
| First Class | first_class ➞ | |
| Priority | priority ➞ | |
| Machinables | machinables ➞ | |
| Irregulars | irregulars ➞ | |
| Parcel Post | parcel_post ➞ | |
| BPM Parcel | bpm_parcel ➞ | |
| Media Mail | media_mail ➞ | |
| BPM Flat | bpm_flat ➞ | |
| Standard Flat | standard_flat ➞ |
Billing Fields
| Name | API value | Domestic / international |
|---|---|---|
| Shipping Payment Type | shipping_payment_type | |
| Billing Account Number | billing_account_number | |
| Billing Account Postal Code | bill_to_postcode | |
| Billing Account Country Code | bill_to_country_code |
Special Services
| Name | API value | Code |
|---|---|---|
| Alternate Delivery Address | alternate_delivery_address | alternate_delivery_address |
| Goods Not In Free Circulation | goods_not_in_free_circulation | goods_not_in_free_circulation |
| MILabelCN22 | mi_label_cn22 | mi_label_cn22 |
| SaturdayDelivery | saturday_delivery | saturday_delivery |
| Saturday Pickup | saturday_pickup | saturday_pickup |
| COD | cod | COD |
| Access Point COD | access_point_cod | AccessPointCOD |
| Deliver To Addressee Only Indicator | deliver_to_addressee_only | deliver_to_addressee_only |
| Direct Delivery Only Indicator | direct_delivery_only | direct_delivery_only |
| CN22 Form | cn22_form | CN22Form |
| UPS Premium Care Form | premium_care_form | UPSPremiumCareForm |
| Additional Document Indicator | additional_document | additional_document |
| Return Of Documents | return_of_documents | return_of_documents |
| Delivery Confirmation | delivery_confirmation | DeliveryConfirmation |
| Import Control | import_control | import_control |
| Commercial Invoice Removal Indicator | commercial_invoice_removal | CommercialInvoiceRemovalIndicator |
| UPS carbon neutral Indicator | ups_carbon_neutral | UPScarbonneutralIndicator |
| SDL Shipment Indicator | sdl_shipment | SDLShipmentIndicator |
| Exchange Forward Indicator | exchange_forward | ExchangeForwardIndicator |
| Dropoff At UPS Facility Indicator | dropoff_at_ups_facility | DropoffAtUPSFacilityIndicator |
| Hold For Pickup Indicator | hold_for_pickup | HoldForPickupIndicator |
| Diagnostic Specimens Indicator | diagnostic_specimens | DiagnosticSpecimensIndicator |
| Alcoholic Beverages Indicator | alcoholic_beverages | AlcoholicBeveragesIndicator |
| Perishables Indicator | perishables | PerishablesIndicator |
| Plants Indicator | plants | PlantsIndicator |
| Seeds Indicator | seeds | SeedsIndicator |
| Special Exceptions Indicator | special_exceptions | SpecialExceptionsIndicator |
| Tobacco Indicator | tobacco | TobaccoIndicator |
| No Transit Times | no_transit_times | NoTransitTime |
| Request List Rates | list_rates | 53 |
| Paperless Trade | paperless_trade | paperless_trade |
Custom Fields
| Name | API value | Required |
|---|---|---|
| Description | description | False |
| Description | description | False |
| Package Type | package_type | False |
| Return Service Code | return_service_code | False |
| Movement Reference Number | movement_reference_number | False |
| Sub Classification | sub_classification | False |
| Cost Center | cost_center | False |
| Cost Center Barcode Indicator | cost_center_barcode | False |
| PackageID | package_id | False |
| Package ID Barcode Indicator | package_id_barcode | False |
| Irregular Indicator | irregular_indicator | False |
| Invoice Line Total Currency Code | ilt_currency_code | False |
| Invoice Line Total Monetary Value | ilt_monetary_value | False |
| EPRA Release Code | epra_release_code | False |
| Clinical Trials ID | clinical_trials_id | False |
| Tax ID Type Code | tax_id_type_code | False |
| Shipment Indication Type Code | shipment_indication_type_code | False |
| HazMat Package Information | haz_mat_package_information | False |
| HazMat Package QValue | haz_mat_package_q_value | False |
| USPS Endorsement | usps_endorsement | False |
References
| Name | API value | Code |
|---|---|---|
| Accounts Receivable Customer Account | accounts_receivable_customer_account | AJ |
| Appropriation Number | appropriation_number | AT |
| Bill of Lading Number | bill_of_lading_number | BM |
| Collect on Delivery (COD) Number | collect_on_delivery_cod_number | 9V |
| Dealer Order Number | dealer_order_number | ON |
| Department Number | department_number | DP |
| Food and Drug Administration (FDA) Product Code | food_and_drug_administration_fda_product_code | 3Q |
| Invoice Number | invoice_number | IK |
| Manifest Key Number | manifest_key_number | MK |
| Model Number | model_number | MJ |
| Part Number | part_number | PM |
| Production Code | production_code | PC |
| Purchase Order Number | purchase_order_number | PO |
| Purchase Request Number | purchase_request_number | RQ |
| Return Authorization Number | return_authorization_number | RZ |
| Salesperson Number | salesperson_number | SA |
| Serial Number | serial_number | SE |
| Store Number | store_number | ST |
| Transaction Reference Number | transaction_reference_number | TN |
| Return Label | barcode | TN |
Example Request / Response
{
"shipment": {
"carrier": "ups",
"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": "ups_next_day_air",
"ship_date": "2022-01-21",
"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": "ups",
"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": "ups_next_day_air",
"ship_date": "2022-01-21",
"shipping_account": "811195730",
"test": true,
"type": "outbound",
"weight_units": "KG"
}
}'
import requests
headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}
payload = {
"shipment": {
"carrier": "ups",
"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": "ups_next_day_air",
"ship_date": "2022-01-21",
"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": "ups",
"shipping_account": "5190163571408896",
"test": true,
"debug": false,
"ship_date": "2022-01-21",
"type": "outbound",
"service": "ups_next_day_air",
"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 | EPL ZPL SPL GIF PDF |
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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection carrier_label_generation_failed carrier_no_shipment_found |
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": "ups",
"shipping_account": "5190163571408896",
"test": true,
"debug": false,
"ship_date": "2022-01-21",
"type": "outbound",
"service": "ups_next_day_air",
"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": {}
}
}
/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).
POST Request Parameters
| Field | Possible Values | Example |
|---|---|---|
| shipment object Definition of the shipment payload required | |
|
| carrier string the carrier name required | fedex |
|
| 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
IN |
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height | 11 |
|
| value number value of the package according to currency specified | 25 |
|
| weight number weight of the package according to units specified under weight_units | 4.2 |
|
| width number width of the package according to units specified under dim_units | 8.5 |
|
| packaging string the packaging type required | your_packaging |
your_packaging |
| recipient object Recipient of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| sender object Sender of shiment required | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string if you specify the service type, you'll get rates only for this service | ups_next_day_air |
|
| ship_date string shipping date required | 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 required | outbound return |
outbound |
| weight_units string Weight units of the packages, pounds or kilograms required | KG LB |
LB |
Successful Response
| Field | Possible Values | Example |
|---|---|---|
| rates array | |
|
| currency string | USD AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GGP GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS IMP INR IQD IRR ISK JEP JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SPL SRD STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TVD TWD TZS UAH UGX UYU UZS VEF VND VUV WST XAF XCD XDR XOF XPF YER ZAR ZMW ZWD |
|
| delivery_day string Day of the week of the delivery. This field is optional depending on the carrier | Mon |
|
| estimated_date string Number of days to ship. This field is optional depending on the carrier | 2021-06-04 |
|
| service_name string carrier supplied name of this service | FedEx Freight |
|
| service_type string service slug which can be used when selecting a service in /ship | ups_next_day_air |
|
| 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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection 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": "ups",
"currency": "EUR",
"debug": true,
"dim_units": "CM",
"packages": [
{
"height": 0,
"length": 2,
"weight": 4,
"width": 3
}
],
"packaging": "your_packaging",
"recipient": {
"city": "Paris",
"country": "FR",
"email": "test@test.com",
"name": "Test",
"phone": "0102030405",
"postal_code": "75008",
"street1": "Place Charles de Gaulle",
"company" : "test",
"street2": ""
},
"sender": {
"city": "CARROS",
"country": "FR",
"email": "test@test.com",
"name": "Test Name",
"phone": "+33 987654321",
"postal_code": "06513",
"company" : "test",
"street1": "1ER AVENUE 14EME RUE BP 148",
"street2": ""
},
"ship_date": "2022-01-21",
"shipping_account": 145964311,
"test": false,
"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": "ups",
"currency": "EUR",
"debug": true,
"dim_units": "CM",
"packages": [
{
"height": 0,
"length": 2,
"weight": 4,
"width": 3
}
],
"packaging": "your_packaging",
"recipient": {
"city": "Paris",
"country": "FR",
"email": "test@test.com",
"name": "Test",
"phone": "0102030405",
"postal_code": "75008",
"street1": "Place Charles de Gaulle",
"company" : "test",
"street2": ""
},
"sender": {
"city": "CARROS",
"country": "FR",
"email": "test@test.com",
"name": "Test Name",
"phone": "+33 987654321",
"postal_code": "06513",
"company" : "test",
"street1": "1ER AVENUE 14EME RUE BP 148",
"street2": ""
},
"ship_date": "2022-01-21",
"shipping_account": 145964311,
"test": false,
"type": "outbound",
"weight_units": "KG"
}
}'
import requests
headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}
payload = {
"shipment": {
"carrier": "ups",
"currency": "EUR",
"debug": true,
"dim_units": "CM",
"packages": [
{
"height": 0,
"length": 2,
"weight": 4,
"width": 3
}
],
"packaging": "your_packaging",
"recipient": {
"city": "Paris",
"country": "FR",
"email": "test@test.com",
"name": "Test",
"phone": "0102030405",
"postal_code": "75008",
"street1": "Place Charles de Gaulle",
"company" : "test",
"street2": ""
},
"sender": {
"city": "CARROS",
"country": "FR",
"email": "test@test.com",
"name": "Test Name",
"phone": "+33 987654321",
"postal_code": "06513",
"company" : "test",
"street1": "1ER AVENUE 14EME RUE BP 148",
"street2": ""
},
"ship_date": "2022-01-21",
"shipping_account": 145964311,
"test": false,
"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())
/track POST
The track endpoint is used to track shipment status as it's being delivered.
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 | af_NA af_ZA ak_GH sq_AL am_ET ar_DZ ar_BH ar_EG ar_IQ ar_JO ar_KW ar_LB ar_LY ar_MA ar_OM ar_QA ar_SA ar_SD ar_SY ar_TN ar_AE ar_YE hy_AM as_IN asa_TZ az_Cyrl az_Cyrl_AZ az_Latn az_Latn_AZ bm_ML eu_ES be_BY bem_ZM bez_TZ bn_BD bn_IN bs_BA bg_BG my_MM yue_Hant_HK ca_ES tzm_Latn tzm_Latn_MA chr_US cgg_UG zh_Hans zh_Hans_CN zh_Hans_HK zh_Hans_MO zh_Hans_SG zh_Hant zh_Hant_HK zh_Hant_MO zh_Hant_TW kw_GB hr_HR cs_CZ da_DK nl_BE nl_NL ebu_KE en_AS en_AU en_BE en_BZ en_BW en_CA en_GU en_HK en_IN en_IE en_IL en_JM en_MT en_MH en_MU en_NA en_NZ en_MP en_PK en_PH en_SG en_ZA en_TT en_UM en_VI en_GB en_US en_ZW et_EE ee_GH ee_TG fo_FO fil_PH fi_FI fr_BE fr_BJ fr_BF fr_BI fr_CM fr_CA fr_CF fr_TD fr_KM fr_CG fr_CD fr_CI fr_DJ fr_GQ fr_FR fr_GA fr_GP fr_GN fr_LU fr_MG fr_ML fr_MQ fr_MC fr_NE fr_RW fr_RE fr_BL fr_MF fr_SN fr_CH fr_TG ff_SN gl_ES lg_UG ka_GE de_AT de_BE de_DE de_LI de_LU de_CH el_CY el_GR gu_IN guz_KE ha_Latn ha_Latn_GH ha_Latn_NE ha_Latn_NG haw_US he_IL hi_IN hu_HU is_IS ig_NG id_ID ga_IE it_IT it_CH ja_JP kea_CV kab_DZ kl_GL kln_KE kam_KE kn_IN kk_Cyrl kk_Cyrl_KZ km_KH ki_KE rw_RW kok_IN ko_KR khq_ML ses_ML lag_TZ lv_LV lt_LT luo_KE luy_KE mk_MK jmc_TZ kde_TZ mg_MG ms_BN ms_MY ml_IN mt_MT gv_GB mr_IN mas_KE mas_TZ mer_KE mfe_MU naq_NA ne_IN ne_NP nd_ZW nb_NO nn_NO nyn_UG or_IN om_ET om_KE ps_AF fa_AF fa_IR pl_PL pt_BR pt_GW pt_MZ pt_PT pa_Arab pa_Arab_PK pa_Guru pa_Guru_IN ro_MD ro_RO rm_CH rof_TZ ru_MD ru_RU ru_UA rwk_TZ saq_KE sg_CF seh_MZ sr_Cyrl sr_Cyrl_BA sr_Cyrl_ME sr_Cyrl_RS sr_Latn sr_Latn_BA sr_Latn_ME sr_Latn_RS sn_ZW ii_CN si_LK sk_SK sl_SI xog_UG so_DJ so_ET so_KE so_SO es_AR es_BO es_CL es_CO es_CR es_DO es_EC es_SV es_GQ es_GT es_HN es_419 es_MX es_NI es_PA es_PY es_PE es_PR es_ES es_US es_UY es_VE sw_KE sw_TZ sv_FI sv_SE gsw_CH shi_Latn shi_Latn_MA shi_Tfng shi_Tfng_MA dav_KE ta_IN ta_LK te_IN teo_KE teo_UG th_TH bo_CN bo_IN ti_ER ti_ET to_TO tr_TR uk_UA ur_IN ur_PK uz_Arab uz_Arab_AF uz_Cyrl uz_Cyrl_UZ uz_Latn uz_Latn_UZ vi_VN vun_TZ cy_GB yo_NG zu_ZA |
en_US |
| refresh boolean whether to force calling live carrier API. By default, we might return a fresh result from the cache | |
|
| shipping_account string Shipping account number required | 5190163571408896 |
|
| test boolean calls created with test = true will be directed to the carrier test servers | |
|
| tracking_number string Tracking number of shipment required | 567293923024 |
|
| webhooks boolean whether to allow webhook functionality for this shipment | |
Successful Response
| Field | Possible Values | Example |
|---|---|---|
| carrier string the carrier name | fedex |
|
| checkpoints array | |
|
| description string | Delivered to a mailbox |
|
| status string the most recent important status description | Delivered to a mailbox |
|
| time string | 2021-06-07T10:46:07.000+1000 |
|
| tracking_stage string the most recent important status standardized shipment stage | CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DELIVERED SHIPMENT_VOIDED EXCEPTION |
DELIVERED |
| delivered boolean whether the shipment was successfully delivered | |
|
| delivery_date string delivery date of this shipment | 2021-06-07T00:00:00.000Z |
|
| estimated_delivery string estimated delivery date of this shipment | 2021-06-07T00:00:00.000Z |
|
| locale string locale used in the checkpoint response. Not all carriers support different languages | af_NA af_ZA ak_GH sq_AL am_ET ar_DZ ar_BH ar_EG ar_IQ ar_JO ar_KW ar_LB ar_LY ar_MA ar_OM ar_QA ar_SA ar_SD ar_SY ar_TN ar_AE ar_YE hy_AM as_IN asa_TZ az_Cyrl az_Cyrl_AZ az_Latn az_Latn_AZ bm_ML eu_ES be_BY bem_ZM bez_TZ bn_BD bn_IN bs_BA bg_BG my_MM yue_Hant_HK ca_ES tzm_Latn tzm_Latn_MA chr_US cgg_UG zh_Hans zh_Hans_CN zh_Hans_HK zh_Hans_MO zh_Hans_SG zh_Hant zh_Hant_HK zh_Hant_MO zh_Hant_TW kw_GB hr_HR cs_CZ da_DK nl_BE nl_NL ebu_KE en_AS en_AU en_BE en_BZ en_BW en_CA en_GU en_HK en_IN en_IE en_IL en_JM en_MT en_MH en_MU en_NA en_NZ en_MP en_PK en_PH en_SG en_ZA en_TT en_UM en_VI en_GB en_US en_ZW et_EE ee_GH ee_TG fo_FO fil_PH fi_FI fr_BE fr_BJ fr_BF fr_BI fr_CM fr_CA fr_CF fr_TD fr_KM fr_CG fr_CD fr_CI fr_DJ fr_GQ fr_FR fr_GA fr_GP fr_GN fr_LU fr_MG fr_ML fr_MQ fr_MC fr_NE fr_RW fr_RE fr_BL fr_MF fr_SN fr_CH fr_TG ff_SN gl_ES lg_UG ka_GE de_AT de_BE de_DE de_LI de_LU de_CH el_CY el_GR gu_IN guz_KE ha_Latn ha_Latn_GH ha_Latn_NE ha_Latn_NG haw_US he_IL hi_IN hu_HU is_IS ig_NG id_ID ga_IE it_IT it_CH ja_JP kea_CV kab_DZ kl_GL kln_KE kam_KE kn_IN kk_Cyrl kk_Cyrl_KZ km_KH ki_KE rw_RW kok_IN ko_KR khq_ML ses_ML lag_TZ lv_LV lt_LT luo_KE luy_KE mk_MK jmc_TZ kde_TZ mg_MG ms_BN ms_MY ml_IN mt_MT gv_GB mr_IN mas_KE mas_TZ mer_KE mfe_MU naq_NA ne_IN ne_NP nd_ZW nb_NO nn_NO nyn_UG or_IN om_ET om_KE ps_AF fa_AF fa_IR pl_PL pt_BR pt_GW pt_MZ pt_PT pa_Arab pa_Arab_PK pa_Guru pa_Guru_IN ro_MD ro_RO rm_CH rof_TZ ru_MD ru_RU ru_UA rwk_TZ saq_KE sg_CF seh_MZ sr_Cyrl sr_Cyrl_BA sr_Cyrl_ME sr_Cyrl_RS sr_Latn sr_Latn_BA sr_Latn_ME sr_Latn_RS sn_ZW ii_CN si_LK sk_SK sl_SI xog_UG so_DJ so_ET so_KE so_SO es_AR es_BO es_CL es_CO es_CR es_DO es_EC es_SV es_GQ es_GT es_HN es_419 es_MX es_NI es_PA es_PY es_PE es_PR es_ES es_US es_UY es_VE sw_KE sw_TZ sv_FI sv_SE gsw_CH shi_Latn shi_Latn_MA shi_Tfng shi_Tfng_MA dav_KE ta_IN ta_LK te_IN teo_KE teo_UG th_TH bo_CN bo_IN ti_ER ti_ET to_TO tr_TR uk_UA ur_IN ur_PK uz_Arab uz_Arab_AF uz_Cyrl uz_Cyrl_UZ uz_Latn uz_Latn_UZ vi_VN vun_TZ cy_GB yo_NG zu_ZA |
en_US |
| status string the most recent important status description | Delivered to a mailbox |
|
| tracking_number string Tracking number of shipment | 567293923024 |
|
| tracking_stage string the most recent important status standardized shipment stage | CREATED PICKED_UP IN_TRANSIT OUT_FOR_DELIVERY DELIVERED SHIPMENT_VOIDED EXCEPTION |
DELIVERED |
Error Response
| Field | Possible Values | Example |
|---|---|---|
| error object | |
|
| code string Standardized error code required | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection carrier_no_shipment_found |
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 |
Available Languages
UPS supports returning tracking responses in a number of languages:
| Name | API value | |
|---|---|---|
| Bulgarian | bg_BG | |
| Czech | cs_CZ | |
| Danish | da_DK | |
| German | de_DE | |
| Greek | el_GR | |
| English (United Kingdom) | en_GB | |
| English (United States) | en_US | |
| Spanish | es_ES | |
| Estonian | et_EE | |
| Finnish | fi_FI | |
| French | fr_FR | |
| Hebrew | he_IL | |
| Hungarian | hu_HU | |
| Italian | it_IT | |
| Japanese | ja_JP | |
| Korean | ko_KR | |
| Lithuanian | lt_LT | |
| Latvian | lv_LV | |
| Dutch | nl_NL | |
| Norwegian | no_NO | |
| Polish | pl_PL | |
| Portuguese | pt_PT | |
| Romanian | ro_RO | |
| Russian | ru_RU | |
| Slovak | sk_SK | |
| Swedish | sv_SE | |
| Turkish | tr_TR | |
| Vietnamese | vi_VN | |
| Chinese | zh_CN | |
| Show more | ||
Example Request / Response
{
"track": {
"test":false,
"carrier": "ups",
"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": "ups",
"shipping_account": 00000000000000,
"tracking_number": "1Z7881280399212000"
}
}'
import requests
headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}
payload = {
"track": {
"test":false,
"carrier": "ups",
"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": "ups",
"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.
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 | af_NA af_ZA ak_GH sq_AL am_ET ar_DZ ar_BH ar_EG ar_IQ ar_JO ar_KW ar_LB ar_LY ar_MA ar_OM ar_QA ar_SA ar_SD ar_SY ar_TN ar_AE ar_YE hy_AM as_IN asa_TZ az_Cyrl az_Cyrl_AZ az_Latn az_Latn_AZ bm_ML eu_ES be_BY bem_ZM bez_TZ bn_BD bn_IN bs_BA bg_BG my_MM yue_Hant_HK ca_ES tzm_Latn tzm_Latn_MA chr_US cgg_UG zh_Hans zh_Hans_CN zh_Hans_HK zh_Hans_MO zh_Hans_SG zh_Hant zh_Hant_HK zh_Hant_MO zh_Hant_TW kw_GB hr_HR cs_CZ da_DK nl_BE nl_NL ebu_KE en_AS en_AU en_BE en_BZ en_BW en_CA en_GU en_HK en_IN en_IE en_IL en_JM en_MT en_MH en_MU en_NA en_NZ en_MP en_PK en_PH en_SG en_ZA en_TT en_UM en_VI en_GB en_US en_ZW et_EE ee_GH ee_TG fo_FO fil_PH fi_FI fr_BE fr_BJ fr_BF fr_BI fr_CM fr_CA fr_CF fr_TD fr_KM fr_CG fr_CD fr_CI fr_DJ fr_GQ fr_FR fr_GA fr_GP fr_GN fr_LU fr_MG fr_ML fr_MQ fr_MC fr_NE fr_RW fr_RE fr_BL fr_MF fr_SN fr_CH fr_TG ff_SN gl_ES lg_UG ka_GE de_AT de_BE de_DE de_LI de_LU de_CH el_CY el_GR gu_IN guz_KE ha_Latn ha_Latn_GH ha_Latn_NE ha_Latn_NG haw_US he_IL hi_IN hu_HU is_IS ig_NG id_ID ga_IE it_IT it_CH ja_JP kea_CV kab_DZ kl_GL kln_KE kam_KE kn_IN kk_Cyrl kk_Cyrl_KZ km_KH ki_KE rw_RW kok_IN ko_KR khq_ML ses_ML lag_TZ lv_LV lt_LT luo_KE luy_KE mk_MK jmc_TZ kde_TZ mg_MG ms_BN ms_MY ml_IN mt_MT gv_GB mr_IN mas_KE mas_TZ mer_KE mfe_MU naq_NA ne_IN ne_NP nd_ZW nb_NO nn_NO nyn_UG or_IN om_ET om_KE ps_AF fa_AF fa_IR pl_PL pt_BR pt_GW pt_MZ pt_PT pa_Arab pa_Arab_PK pa_Guru pa_Guru_IN ro_MD ro_RO rm_CH rof_TZ ru_MD ru_RU ru_UA rwk_TZ saq_KE sg_CF seh_MZ sr_Cyrl sr_Cyrl_BA sr_Cyrl_ME sr_Cyrl_RS sr_Latn sr_Latn_BA sr_Latn_ME sr_Latn_RS sn_ZW ii_CN si_LK sk_SK sl_SI xog_UG so_DJ so_ET so_KE so_SO es_AR es_BO es_CL es_CO es_CR es_DO es_EC es_SV es_GQ es_GT es_HN es_419 es_MX es_NI es_PA es_PY es_PE es_PR es_ES es_US es_UY es_VE sw_KE sw_TZ sv_FI sv_SE gsw_CH shi_Latn shi_Latn_MA shi_Tfng shi_Tfng_MA dav_KE ta_IN ta_LK te_IN teo_KE teo_UG th_TH bo_CN bo_IN ti_ER ti_ET to_TO tr_TR uk_UA ur_IN ur_PK uz_Arab uz_Arab_AF uz_Cyrl uz_Cyrl_UZ uz_Latn uz_Latn_UZ vi_VN vun_TZ cy_GB yo_NG zu_ZA |
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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection carrier_no_shipment_found |
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 POST
The pickup endpoint allows you to schedule pickups for one or more shipments.
POST Request Parameters
| Field | Possible Values | Example |
|---|---|---|
| pickup object required | |
|
| carrier string the carrier name required | fedex |
|
| 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| description string | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
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 | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| 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 |
|
| shipments array required | |
|
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height | 11 |
|
| value number value of the package according to currency specified | 25 |
|
| weight number weight of the package according to units specified under weight_units | 4.2 |
|
| width number width of the package according to units specified under dim_units | 8.5 |
|
| recipient object Recipient of shiment | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string the service type | ups_next_day_air |
|
| 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 | 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| description string | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
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 | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| 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 |
|
| shipments array required | |
|
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height | 11 |
|
| value number value of the package according to currency specified | 25 |
|
| weight number weight of the package according to units specified under weight_units | 4.2 |
|
| width number width of the package according to units specified under dim_units | 8.5 |
|
| recipient object Recipient of shiment | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string the service type | ups_next_day_air |
|
| 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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection ship_date_past invalid_phone_number |
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": "ups",
"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": "ups",
"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": "ups",
"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": "ups",
"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.
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 | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| 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 | 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.4357512173 |
|
| lng string longitude | 36.0897889171 |
|
| 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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection |
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": "ups",
"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": "ups",
"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": "ups",
"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"
}
]
}
/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.
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 | 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 |
|
| debug boolean calls with debug=true will be logged | |
|
| description string | |
|
| dim_units string Dimension units of the packages, inches or centimeters required | CM IN |
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 | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| 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 |
|
| ready_time string Reserved for future use | 2021-06-04 |
|
| shipments array required | |
|
| packages array required | |
|
| height number height of the package according to units specified under dim_units | 5 |
|
| length number length of the package according to units specified under dim_units. ususally the length needs to be the largest of length, width, height | 11 |
|
| value number value of the package according to currency specified | 25 |
|
| weight number weight of the package according to units specified under weight_units | 4.2 |
|
| width number width of the package according to units specified under dim_units | 8.5 |
|
| recipient object Recipient of shiment | |
|
| city string the city of the recipient required | Burlington |
|
| company string the company name of the recipient | Burlington Textiles Corp of America |
|
| country string required | AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW |
US |
| email string the email address of the recipient | jrogers@example.com |
|
| name string the name of the recipient required | Jack O'Rogers |
|
| phone string the phone number of the recipient | (336) 222-7000 |
|
| postal_code string the postal code / zip number of the recipient. Specific format depends on the country | 27215 |
|
| state string the state of the recipient | NC |
|
| street1 string the first line of the street address of the recipient required | 525 S. ZENKRAFT Ave |
|
| street2 string the second line of the street address of the recipient | suite 120 |
|
| service string the service type | ups_next_day_air |
|
| 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 | CM IN |
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 | missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception missing_api_key wrong_api_key shipping_account_not_found shipping_account_wrong_carrier schema_validation_error schema_field_required unexpected_exception carrier_exception carrier_authentication carrier_http_exception carrier_throttling carrier_unsupported_method carrier_timeout carrier_failed_connection ship_date_past invalid_phone_number |
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": "ups",
"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": "ups_next_day_air"
}
],
"shipping_account": 197299590,
"test": true,
"weight_units": "LB",
"start_date": "2022-01-21",
"end_date": "2022-01-21"
}
}
curl --request POST \
--url https://api.zenkraft.com/pickup/availability \
--header 'content-type: application/json' \
--header 'zkkey: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
"pickup_availability": {
"carrier": "ups",
"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": "ups_next_day_air"
}
],
"shipping_account": 197299590,
"test": true,
"weight_units": "LB",
"start_date": "2022-01-21",
"end_date": "2022-01-21"
}
}'
import requests
headers = {
"zkkey": "XXXXXXXXXXXXXXXXXXXXXXX"
}
payload = {
"pickup_availability": {
"carrier": "ups",
"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": "ups_next_day_air"
}
],
"shipping_account": 197299590,
"test": true,
"weight_units": "LB",
"start_date": "2022-01-21",
"end_date": "2022-01-21"
}
}
url = "https://api.zenkraft.com/pickup/availability"
response = requests.request(url=url, method='POST', json=payload, headers=headers)
print(response.json())
{
"pickup_availability": {
"carrier": "ups",
"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": "ups_next_day_air"
}
],
"shipping_account": 197299590,
"test": true,
"weight_units": "LB",
"start_date": "2022-01-21",
"end_date": "2022-01-21",
"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"
}
]
}
}
/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
POST Request Parameters
| Field | Possible Values | Example |
|---|---|---|
| webhook object required | |
|
| api_version string The webhook version. Used for future compatibility | v1 |
|
| callback string URL of the receiving endpoint required | https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508 |
|
| debug boolean calls with debug=true will be logged | |
|
| description string Webhook description | |
|
| events array Events to receive. If left empty, it's assumed you want to receive all the events | shipment.created shipment.picked_up shipment.in_transit shipment.out_for_delivery shipment.delivered shipment.shipment_voided shipment.exception |
shipment.delivered |
| format string Currently only JSON is supported. Used for future compatibility | json |
|
| name string Webhook name | |
Successful Response
| Field | Possible Values | Example |
|---|---|---|
| webhook object | |
|
| api_version string The webhook version. Used for future compatibility | v1 |
|
| callback string URL of the receiving endpoint required | https://webhook.site/3a788dd3-bd7c-44a8-bae0-297e3b68b508 |
|
| debug boolean calls with debug=true will be logged | |
|
| description string Webhook description | |
|
| events array Events to receive. If left empty, it's assumed you want to receive all the events | shipment.created shipment.picked_up shipment.in_transit shipment.out_for_delivery shipment.delivered shipment.shipment_voided shipment.exception |
shipment.delivered |
| format string Currently only JSON is supported. Used for future compatibility | json |
|
| id string ID of the subscription | 484fe753dcda47a1b817456f3a10e38e |
|
| name string Webhook name | |
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",
}
}
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",
}
}'
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",
}
}
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"
}
}Object References
manifest_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
webhook_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
_webhook_response
| Field | Type | Required | Min Length | Max Length |
| name | string | - | - | |
| format | string | - | - | |
| id | string | - | - | |
| callback | string | True | - | - |
| debug | boolean | - | - | |
| events | array | - | - | |
| api_version | string | - | - | |
| description | string | - | - |
pickup_availability_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
label_type
the label format of the shipping labels
| Field | Type | Required | Min Length | Max Length |
rate_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
location
| Field | Type | Required | Min Length | Max Length |
| city | string | True | - | 35 |
| name | string | True | - | 35 |
| street1 | string | True | - | 35 |
| street2 | string | - | 35 | |
| phone | string | 10 | 15 | |
| state | string | - | 35 | |
| postal_code | string | - | 20 | |
| country | string | True | - | - |
| company | string | - | 35 | |
| string | - | - |
successful_response
| Field | Type | Required | Min Length | Max Length |
| success | object | True | - | - |
updated
when was this object updated
| Field | Type | Required | Min Length | Max Length |
webhook
| Field | Type | Required | Min Length | Max Length |
| name | string | - | - | |
| format | string | - | - | |
| callback | string | True | - | - |
| debug | boolean | - | - | |
| events | array | - | - | |
| api_version | string | - | - | |
| description | string | - | - |
dopu
| Field | Type | Required | Min Length | Max Length |
| test | boolean | - | - | |
| debug | boolean | - | - | |
| carrier | string | True | - | - |
| location | object | - | - | |
| shipping_account | string | True | - | - |
recipient
Recipient of shiment
| Field | Type | Required | Min Length | Max Length |
| city | string | True | - | 35 |
| name | string | True | - | 35 |
| street1 | string | True | - | 35 |
| street2 | string | - | 35 | |
| string | - | - | ||
| phone | string | 10 | 15 | |
| state | string | - | 35 | |
| postal_code | string | - | 20 | |
| country | string | True | - | - |
| company | string | - | 35 |
__track
| Field | Type | Required | Min Length | Max Length |
| shipping_account | string | True | - | - |
| locale | string | - | - | |
| refresh | boolean | - | - | |
| debug | boolean | - | - | |
| carrier | string | True | - | - |
| checkpoints | boolean | - | - | |
| test | boolean | - | - | |
| webhooks | boolean | - | - |
manifest_get_response
| Field | Type | Required | Min Length | Max Length |
| manifest | True | - | - |
UserBase
| Field | Type | Required | Min Length | Max Length |
| company | string | True | - | - |
| name | string | True | - | - |
| string | True | - | - |
pickup_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
shipping_account
Shipping account number
| Field | Type | Required | Min Length | Max Length |
countries
| Field | Type | Required | Min Length | Max Length |
shipment_status_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
manifest_id
carrier ID of this manifest which can be used in GET on /manifest/<manifest_id>
| Field | Type | Required | Min Length | Max Length |
shippingaccount_response
Carrier credentials
| Field | Type | Required | Min Length | Max Length |
| shipping_account | object | True | - | - |
connected_account_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
debug
calls with debug=true will be logged
| Field | Type | Required | Min Length | Max Length |
rate_response
| Field | Type | Required | Min Length | Max Length |
| rates | array | True | - | - |
ReturnMethod
| Field | Type | Required | Min Length | Max Length |
| display_name | string | True | - | - |
| type | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| return_charge | string | True | - | - |
| method_name | string | True | - | - |
| filters | array | True | - | - |
| service_type | string | True | - | - |
| position | integer | True | - | - |
| location_id | string | True | - | - |
| id | string | True | - | - |
locale
requested locale
| Field | Type | Required | Min Length | Max Length |
pickup_response
| Field | Type | Required | Min Length | Max Length |
| pickup | object | True | - | - |
rate
Definition of the shipment payload
| Field | Type | Required | Min Length | Max Length |
| weight_units | string | True | - | - |
| packaging | string | True | - | - |
| packages | array | True | - | - |
| sender | object | True | - | - |
| shipping_account | string | True | - | - |
| currency | string | - | - | |
| special_services | array | - | - | |
| ship_date | string | True | - | - |
| debug | boolean | - | - | |
| carrier | string | True | - | - |
| type | string | True | - | - |
| test | boolean | - | - | |
| dim_units | string | True | - | - |
| recipient | object | True | - | - |
| service | string | - | - |
location_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
Location
| Field | Type | Required | Min Length | Max Length |
| city | string | True | - | 35 |
| updated | string | - | - | |
| name | string | True | - | 35 |
| street1 | string | True | - | 35 |
| street2 | string | - | 35 | |
| id | string | True | - | - |
| phone | string | True | 10 | 15 |
| state | string | True | - | 35 |
| cutoff_hours | integer | - | - | |
| postal_code | string | True | - | 20 |
| company | string | True | - | 35 |
| cutoff_minutes | integer | - | - | |
| timezone | string | - | - | |
| country | string | True | - | - |
| type | string | True | - | - |
| string | True | - | - |
shipment_status_pending_response
| Field | Type | Required | Min Length | Max Length |
| shipment | True | - | - |
webhook_list_response
| Field | Type | Required | Min Length | Max Length |
| webhooks | array | True | - | - |
manifest_list_response
| Field | Type | Required | Min Length | Max Length |
| manifests | array | True | - | - |
manifest_post_response
| Field | Type | Required | Min Length | Max Length |
| manifest | True | - | - |
shippingaccount_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
ConnectedAccountBase
| Field | Type | Required | Min Length | Max Length |
| shipping_account_id | integer | True | - | - |
| ftp_password | string | True | - | - |
| name | string | True | - | - |
| service | integer | True | - | - |
| ftp_username | string | True | - | - |
pickup
| Field | Type | Required | Min Length | Max Length |
| shipments | array | True | - | - |
| weight_units | string | True | - | - |
| description | string | - | - | |
| shipping_account | string | True | - | - |
| debug | boolean | - | - | |
| currency | string | - | - | |
| carrier | string | True | - | - |
| location | object | True | - | - |
| time | object | True | - | - |
| test | boolean | - | - | |
| dim_units | string | True | - | - |
shipment
Definition of the shipment payload
| Field | Type | Required | Min Length | Max Length |
| weight_units | string | True | - | - |
| ship_date | string | True | - | - |
| dim_units | string | True | - | - |
| sender | object | True | - | - |
| shipping_account | string | True | - | - |
| notifications | array | - | - | |
| type | string | True | - | - |
| recipient | object | True | - | - |
| label_type | string | True | - | - |
| include_base64_label | boolean | - | - | |
| packaging | string | True | - | - |
| currency | string | - | - | |
| carrier | string | True | - | - |
| references | array | - | - | |
| debug | boolean | - | - | |
| packages | array | True | - | - |
| special_services | array | - | - | |
| service | string | True | - | - |
| test | boolean | - | - |
pickup_availability_response
| Field | Type | Required | Min Length | Max Length |
| pickup_availability | object | True | - | - |
SalesforceCore
| Field | Type | Required | Min Length | Max Length |
| environment | string | True | - | - |
| custom_domain | string | True | - | - |
| service | integer | True | - | - |
ShipmentEvent
| Field | Type | Required | Min Length | Max Length |
| service | string | True | - | - |
| created | string | True | - | - |
| tracking_number | string | True | - | - |
| from_country | string | True | - | - |
| currency | string | True | - | - |
| to_country | string | True | - | - |
| carrier | string | True | - | - |
| is_outbound | boolean | True | - | - |
| total_costs | number | True | - | - |
FtpConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| name | string | True | - | - |
| ftp_password | string | True | - | - |
| ftp_username | string | True | - | - |
| service | integer | True | - | - |
| shipping_account_id | integer | True | - | - |
shipment_status
Standardized shipment status
| Field | Type | Required | Min Length | Max Length |
dopu_response
| Field | Type | Required | Min Length | Max Length |
| locations | array | True | - | - |
packages
We need to know the size and dimensions of your packages.
| Field | Type | Required | Min Length | Max Length |
| width | number | - | - | |
| length | number | - | - | |
| weight | number | True | - | - |
| value | number | - | - | |
| height | number | - | - |
base_shipment
Definition of the shipment payload
| Field | Type | Required | Min Length | Max Length |
| weight_units | string | True | - | - |
| packaging | string | True | - | - |
| packages | array | True | - | - |
| sender | object | True | - | - |
| shipping_account | string | True | - | - |
| currency | string | - | - | |
| special_services | array | - | - | |
| ship_date | string | True | - | - |
| debug | boolean | - | - | |
| carrier | string | True | - | - |
| type | string | True | - | - |
| test | boolean | - | - | |
| dim_units | string | True | - | - |
| recipient | object | True | - | - |
| service | string | - | - |
created
when was this object created
| Field | Type | Required | Min Length | Max Length |
carrier
the carrier name
| Field | Type | Required | Min Length | Max Length |
_pickup
| Field | Type | Required | Min Length | Max Length |
| shipments | array | True | - | - |
| weight_units | string | True | - | - |
| description | string | - | - | |
| shipping_account | string | True | - | - |
| test | boolean | - | - | |
| currency | string | - | - | |
| carrier | string | True | - | - |
| location | object | True | - | - |
| time | object | True | - | - |
| debug | boolean | - | - | |
| dim_units | string | True | - | - |
FtpConnectedAccountCredentials
| Field | Type | Required | Min Length | Max Length |
| ftp_password | string | True | - | - |
| ftp_username | string | True | - | - |
shipping_documents
Additional information about packages
| Field | Type | Required | Min Length | Max Length |
| document_type | string | True | - | - |
| description | string | True | - | - |
| document | string | True | - | - |
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 | - | - |
ship_response
| Field | Type | Required | Min Length | Max Length |
| shipment | object | True | - | - |
shipment_status_success_response
| Field | Type | Required | Min Length | Max Length |
| shipment | True | - | - |
weight_units
Weight units of the packages, pounds or kilograms
| 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 |
track_response
| Field | Type | Required | Min Length | Max Length |
| status | string | - | - | |
| delivered | boolean | - | - | |
| tracking_stage | string | - | - | |
| estimated_delivery | string | - | - | |
| locale | string | - | - | |
| tracking_number | string | - | - | |
| carrier | string | - | - | |
| checkpoints | array | - | - | |
| delivery_date | string | - | - |
service
the service type
| Field | Type | Required | Min Length | Max Length |
__pickup
| Field | Type | Required | Min Length | Max Length |
| shipments | array | True | - | - |
| weight_units | string | True | - | - |
| description | string | - | - | |
| shipping_account | string | True | - | - |
| currency | string | - | - | |
| debug | boolean | - | - | |
| carrier | string | True | - | - |
| location | object | True | - | - |
| test | boolean | - | - | |
| dim_units | string | True | - | - |
User
| Field | Type | Required | Min Length | Max Length |
| total_7_days | integer | True | - | - |
| name | string | True | - | - |
| created | string | True | - | - |
| total_28_days | integer | True | - | - |
| string | True | - | - | |
| total_1_day | integer | True | - | - |
| api_key | string | True | - | - |
| company | string | True | - | - |
customs_items
Additional information about packages
| Field | Type | Required | Min Length | Max Length |
| value | number | True | - | - |
| description | string | True | - | - |
| weight | number | True | - | - |
| quantity | integer | True | - | - |
dim_units
Dimension units of the packages, inches or centimeters
| Field | Type | Required | Min Length | Max Length |
return_method_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
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 | - | - |
ConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| status | string | True | - | - |
| ftp_username | string | True | - | - |
| service | integer | True | - | - |
| shipping_account_id | integer | True | - | - |
| ftp_password | string | True | - | - |
| id | string | True | - | - |
| name | string | True | - | - |
tracking_stage
the most recent important status standardized shipment stage
| Field | Type | Required | Min Length | Max Length |
NewstoreConnectedAccount
| Field | Type | Required | Min Length | Max Length |
| shipping_account_id | integer | True | - | - |
| service | integer | True | - | - |
| name | string | True | - | - |
tracking_number
Tracking number of shipment
| Field | Type | Required | Min Length | Max Length |
track_by_reference_number
| Field | Type | Required | Min Length | Max Length |
| reference_number | string | True | - | - |
| shipping_account | string | True | - | - |
| locale | string | - | - | |
| refresh | boolean | - | - | |
| test | boolean | - | - | |
| carrier | string | True | - | - |
| checkpoints | boolean | - | - | |
| debug | boolean | - | - | |
| webhooks | boolean | - | - |
error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
shipment_id
shipment ID
| Field | Type | Required | Min Length | Max Length |
_shipment_status_response
| Field | Type | Required | Min Length | Max Length |
| shipment | True | - | - |
LocationBase
| Field | Type | Required | Min Length | Max Length |
| city | string | True | - | 35 |
| name | string | True | - | 35 |
| street1 | string | True | - | 35 |
| street2 | string | - | 35 | |
| cutoff_minutes | integer | - | - | |
| string | True | - | - | |
| phone | string | True | 10 | 15 |
| state | string | True | - | 35 |
| cutoff_hours | integer | - | - | |
| postal_code | string | True | - | 20 |
| country | string | True | - | - |
| timezone | string | - | - | |
| type | string | True | - | - |
| company | string | True | - | 35 |
webhook_id
ID of the subscription
| Field | Type | Required | Min Length | Max Length |
track_by_tracking_number
| Field | Type | Required | Min Length | Max Length |
| shipping_account | string | True | - | - |
| locale | string | - | - | |
| refresh | boolean | - | - | |
| test | boolean | - | - | |
| tracking_number | string | True | - | - |
| carrier | string | True | - | - |
| checkpoints | boolean | - | - | |
| debug | boolean | - | - | |
| webhooks | boolean | - | - |
cancel_pickup
| Field | Type | Required | Min Length | Max Length |
| test | boolean | - | - | |
| debug | boolean | - | - | |
| confirmation_number | string | True | - | - |
| carrier | string | True | - | - |
| shipping_account | string | True | - | - |
LogDetails
| Field | Type | Required | Min Length | Max Length |
| created | string | - | - | |
| url | string | - | - | |
| status_code | number | - | - | |
| request | object | True | - | - |
| response | object | True | - | - |
| http_method | string | True | - | - |
| user_agent | string | True | - | - |
| content_type | string | True | - | - |
| ip_address | string | - | - | |
| id | string | - | - |
dopu_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
status
the most recent important status description
| Field | Type | Required | Min Length | Max Length |
currencies
| Field | Type | Required | Min Length | Max Length |
track
| Field | Type | Required | Min Length | Max Length |
| shipping_account | string | True | - | - |
| locale | string | - | - | |
| refresh | boolean | - | - | |
| debug | boolean | - | - | |
| tracking_number | string | True | - | - |
| carrier | string | True | - | - |
| checkpoints | boolean | - | - | |
| test | boolean | - | - | |
| webhooks | boolean | - | - |
log_item
| Field | Type | Required | Min Length | Max Length |
| url | string | - | - | |
| status_code | number | - | - | |
| ip_address | string | - | - | |
| id | string | - | - | |
| created | string | - | - |
ReturnMethodBase
| Field | Type | Required | Min Length | Max Length |
| display_name | string | True | - | - |
| location_id | string | True | - | - |
| shipping_account_id | integer | True | - | - |
| method_name | string | True | - | - |
| filters | array | True | - | - |
| position | integer | True | - | - |
| service_type | string | True | - | - |
| return_charge | string | True | - | - |
| type | string | True | - | - |
SalesforceCommerceCloud
| Field | Type | Required | Min Length | Max Length |
| url | string | True | - | - |
| service | integer | True | - | - |
webhook_response
| Field | Type | Required | Min Length | Max Length |
| webhook | object | - | - |
track_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |
costs
Additional information about packages
| Field | Type | Required | Min Length | Max Length |
| base_charge | number | - | - | |
| net_charge | number | - | - | |
| surcharges | number | - | - | |
| taxes | number | - | - | |
| discounts | number | - | - |
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 |
ship_error
| Field | Type | Required | Min Length | Max Length |
| error | object | True | - | - |