CSV API Documentation

Authentication

Authentication and identification to the Zenfulfillment API are done by providing an API Key on every request as your Basic Auth username (no password is required). Zenfulfillment requires that all communication with the API is secured using TLS v1.2. (Requests made over HTTP or without a proper API Key will fail)

You can request your API Keys at support@zenfulfillment.com

Treat your API Keys as passwords & keep them secret. API Keys give full read/write access to your account, so they should not be included in public repositories, emails, client-side code, etc.

cURL Authorization example:

curl https://api.zenfulfillment.com/orders/import -H 'Authorization: ZF-API <API-TOKEN-HERE>':

POST /orders/import

Post a CSV File containing all orders to import. CSV row with Reference already existing in the integration will update the order. If the Reference doesn't exist in our system, an order will be created in the integration with that Reference. CSV file containing errors for some orders would still create/update the orders with valid data, but return back errors with the orders which failed.

Blank CSV – Download and complete

Sample File with explanations: Order Data

Excel with Export macro: Download

Example Request:

curl -X POST 'https://api.zenfulfillment.com/orders/import' -F 'file=@orders-test.csv;type=text/csv' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

CSV columns:

  • Reference (required) - order reference in the store | STRING | e.g O918771
  • Date (required) - date when the order was placed in the store | DD:MM:YYYY HH:MM:ss | e.g 11.10.2020 11:39:43
  • Name (required) - full name of user that placed the order | STRING | e.g Jane Smith
  • Company (required) - user company name | STRING | e.g Zenfulfillment
  • Street1 (required) - shipping street address | STRING | e.g Münzstraße 55
  • Street2 (optional) - shipping street address | STRING | e.g c/o Zen
  • Zip Code (required) - shipping billing zip code | STRING | e.g 10991
  • City (required) - shipping city | STRING | e.g Berlin
  • Region (required) - shipping region | STRING | e.g Berlin
  • Country (required) - shipping country | STRING | e.g Deutschland
  • Email (required) - user email | STRING | e.g jane.smith@example.com
  • Phone (required) - user phone number | STRING | e.g +4999111223319
  • SKU (required) - ordered product sku in store | STRING | e.g MP-001
  • Quantity (required) - quantity of ordered product | Number | e.g 6
  • Note (optional) - order note | STRING | e.g This is a note
  • OrderTotalCost (optional) - total cost of order | Number | e.g 120,81
  • Shippingoption (optional) - shipping option chosen on the store | STRING |  e.g GLS (This column is optional and usually has to be empty, Zen will automatically calculate the best shipping option for your orders.)
  • PaymentMethod (optional) - payment method of the order | STRING | Accepted values: COD

Example Response:

When all orders in the CSV are processed successfully the response has the following structure

[
  {
    reference: 0991,
    shipping: {
      address: {
        name: "Franziska Fabry",
        street: "Münzstraße 6",
	zip: "10199",
	city: "Brackenheim",
 	country: "DE"
      }
    },
    products: [
	{
	  sku: "sku-123",
	  quantity_ordered: 2
	  ...
	}
   ]
  created_at: "2020-10-11T22:00:00.000Z"
]

If there are errors while processing, we do not reject the whole batch immediately - instead we will try to process all and return the list of respective errors or successfully processed list of orders. In the scenario the return object would be in the form:

{
statusCode: 422,
error: "Unprocessable Entity",
message: "Import CSV succeeded partially, please check the errors",
errors: [
  {
    "reference": "0991",
    "error": "SKU-123 is missing"
  }
]
orders: [
  {
    reference: 0991,
    shipping: {
      address: {         
        name: "Franziska Fabry",        
        street: "Münzstraße 6", 	
        zip: "10199", 	
        city: "Brackenheim",  	
        country: "DE"       
      }     
    },     
    products: [ 	
      { 	  
        sku: "sku-123", 	  
        quantity_ordered: 2 	  
        ... 	
      }     
   ]   
   created_at: "2020-10-11T22:00:00.000Z"
]
}

Example CSV:

Reference;Date;Company;Name;Street1;Street2;Zip Code;City;Region;Country;SKU;Quantity;Note;OrderTotalCost;Shippingoption
O991;11.10.2020 20:27:16;;Franziska Fabry;Münzstrasse 6; ;10199;Brackenheim;Brackenheim;DE;sku-123;2;This is a note;120,81;GLS
O991;11.10.2020 20:27:16;;Franziska Fabry;Münzstrasse 6; ;10199;Brackenheim;Brackenheim;DE;sku-321;2;This is a note;120,81;GLS

GET /orders/export

Exports a CSV File containing all orders that match the filters.

Download Sample File: Order Export Data

Example Request: 

curl 'https://api.zenfulfillment.com/orders/export' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

Parameters:

  • createdAtMin - in ISO8601 format. Show orders created at or after date.
  • createdAtMax - in ISO8601 format Show orders created at or before date.
  • updatedAtMin - in ISO8601 format Show orders last updated at or after date.
  • updatedAtMax - in ISO8601 format Show orders last updated at or before date.
  • page - the default page is 1, you can paginate specifying 2, 3, etc.
  • perPage - the default limit is 10 results per page, you can specify 20, 30, up to 50 max.
  • q - this is for searching, you can search by any value, and the search will automatically search across many order data points, (shipping address like street, city, country, zip code, customer name, order number or zf number)
  • status - you can filter for a specific status. the allowed values are: UNKNOWN, NOT_PAID, INVALID_ADDRESS, PENDING, PROCESSING, PICKED, PACKING, PACKED, SHIPPED, CANCELLED. Note: You can only filter by 1 status at a time.

You can combine all previous parameters together if you need.

Example Request:

curl 'https://api.zenfulfillment.com/orders/export?updatedAtMin=2019-12-31T00:00:00.000Z&page=2&perPage=30&q=Markus&status=PENDING' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

This example will export all orders with the following filters:

- update date greater or equal to 2019-12-31T00:00:00.000Z
- status PENDING
- up to 30 results per page
- page 2 results
- orders matching the customer "Markus"

GET /orders/external/{reference}

Returns an order that is matching this order external reference in connected store.

Example Request: 

curl 'https://api.zenfulfillment.com/orders/external/332-11-5599' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

POST /orders/cancel

Cancels one or more orders based on the list ZF reference provided through CSV. This will cancel the orders which are cancellable, as well as return the errors for those which were not cancelled.

Download Sample File: Cancel Orders via CSV

Example Request: 

curl -X POST 'https://api.zenfulfillment.com/orders/cancel' -F 'file=@cancel-orders.csv;type=text/csv' -H 'Authorization: ZF-API <API-TOKEN-HERE>'<br>
	

CSV Columns:
  • Reference - the ZF order reference is a mandatory parameter

POST /products/import

Post a CSV containing all products that shall be created or updated. CSV row with SKU already existing in the integration will update the product. If the SKU doesn't exist, a product will be created in the integration.

Download Sample File: Product Data

Example Request: 

curl -X POST 'https://api.zenfulfillment.com/products/import' -F 'file=@products-test.csv;type=text/csv' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

CSV Columns:

  • SKU - product sku in store | STRING | e.g. MP-001
  • Name - name of the product | STRING | e.g. Stainless Steel Bottle
  • Description (optional) - description of the product | STRING | e.g. Stainless Steel Bottle 500ml
  • Barcode (optional) - barcode of the product | Number | e.g. 1234567834.
  • Weight (optional) - the weight of the product | Number | e.g. 1, 1.2.
  • Length (optional) - the weight of the product | Number | e.g. 10.
  • Width (optional) - the weight of the product | Number | e.g. 20.
  • Height (optional) - the weight of the product | Number | e.g. 15.
  • Price (optional) -  the price of the product | Number | e.g. 1,20.
  • Image (optional) - the image of the product | STRING | e.g. 'https://test.abc.com/files/IMG_3149-fin.jpg'.

GET /products/export

Exports a CSV File containing all products stock levels.

Download Sample File: Stock Levels

Example Request:

curl -X GET 'https://api.zenfulfillment.com/products/export' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

POST /inventory_shipments/import

Post a CSV containing all inventory shipments that shall be created.

Download Sample File: Inventory Shipment

Example Request: 

curl -X POST 'https://api.zenfulfillment.com/inventory_shipment/import' -F 'file=@inv_shipment-test.csv;type=text/csv' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

PUT /inventory_shipments/{reference}/import

Updates an inventory shipment via CSV containing products related to the inventory shipments. If the CSV contains the existing products, only the new quantity will be updated, else the quantity would be set to 0. If the csv contains products which do not exist in the previous inventory shipment, those will be added as new products to the inventory shipment.

Download Sample File: Inventory Shipment

Example Request: 

curl -X PUT 'https://api.zenfulfillment.com/inventory_shipments/{reference}/import' -F 'file=@inv_shipment-update.csv;type=text/csv' -H 'Authorization: ZF-API <API-TOKEN-HERE>'

GET /inventory_shipments/export

Exports a CSV File containing all inventory shipments that match the filters.
Download Sample File: Export Inventory Shipments
Example Request: 
curl -X GET 'https://api.zenfulfillment.com/inventory_shipments/export' -H 'Authorization: ZF-API <API-TOKEN-HERE>'
		
Parameters:
  • createdAtMin - in ISO8601 format, shows orders created at or after date
  • createdAtMax - in ISO8601 format, shows orders created at or before date
  • updatedAtMin - in ISO8601 format, shows orders last updated at or after date
  • updatedAtMax - in ISO8601 format, shows orders last updated at or before date
  • page - the default page is 1, you can paginate specifying 2, 3, etc.
  • perPage - the default limit is 10 results per page, you can specify 20, 30, up to 50 max.
  • q - this is for searching, you can search by any value, and the search will automatically search across all inventory shipment data points, (zf number, tracking code, type, etc.)
  • status - you can filter for a specific status. the allowed values are: PENDING, CANCELLED, STORED, PARTIALLY_STORED, PROCESSING, RECEIVED. Note: You can only filter by 1 status at a time.
You can combine all previous parameters together if you need.
Example Request:
curl -X GET 'https://api.zenfulfillment.com/inventory_shipments/export?updatedAtMin=2019-12-31T00:00:00.000Z&page=2&perPage=30&q=pallets&status=PENDING' -H 'Authorization: ZF-API <API-TOKEN-HERE>'<br>
		
This example will export all orders with the following filters:
  • update date greater or equal to 2019-12-31T00:00:00.000Z
  • status PENDING
  • up to 30 results per page
  • page 2 results
  • orders matching the inventory shipment type "pallets"

GET /inventory_shipments/export/{reference}/reference

Exports a CSV File containing the single inventory shipment that was requested.

Download Sample File: Export An Inventory Shipment
Example Request: 
curl -X GET 'https://api.zenfulfillment.com/inventory_shipments/export/{reference}/reference' -H 'Authorization: ZF-API <API-TOKEN-HERE>'<br>
	
Parameters:
  • reference - the ZF order reference is a mandatory parameter
Example Request:
curl -X GET 'https://api.zenfulfillment.com/inventory_shipments/export/ZF01124058/reference' -H 'Authorization: ZF-API <API-TOKEN-HERE>'<br>
		

This example will export the inventory shipment ZF01124058 with all the existing products data.

GET /returns/export

Exports a CSV file containing all available returns matching the specified filters.

Parameters:

  • createdAtMin - in ISO8601 format. Show returns created at or after date.
  • createdAtMax - in ISO8601 format Show returns created at or before date.
  • updatedAtMin - in ISO8601 format Show returns last updated at or after date.
  • updatedAtMax - in ISO8601 format Show returns last updated at or before date.
  • page - the default page is 1, you can paginate specifying 2, 3, etc.
  • perPage - the default limit is 10 results per page, you can specify 20, 30, up to 50 max.
  • q - this is for searching, you can search by any value, and the search will automatically search across many return data points, including related order data (shipping address like street, city, country, zip code, customer name, order number or zf number)
  • status - you can filter for a specific status. the allowed values are: PROCESSED, DONE. Note: You can only filter by 1 status at a time.

You can combine all previous parameters together if you need.

Example Request: 

curl https://api.zenfulfillment.com/returns/export -H 'Authorization: ZF-API <API-TOKEN-HERE>'

Example Request:

curl https://api.zenfulfillment.com/api/returns/export?from=2019-09-30T22:00:00.000Z&to=2019-10-10T14:45:02.408Z -H 'Authorization: ZF-API <API-TOKEN-HERE>'

Search returns

- You can also export all returns that match a certain search query, for example:

curl https://api.zenfulfillment.com/api/returns/export?q=John -H 'Authorization: ZF-API <API-TOKEN-HERE>'

- Export returns that are both limited by a search query and by date rage:

curl https://api.zenfulfillment.com/api/returns/export?q=John&from=2019-09-30T22:00:00.000Z&to=2019-10-10T14:45:02.408Z -H 'Authorization: ZF-API <API-TOKEN-HERE>'

POST /returns/{returnId}/done 

Updates a return as refunded.

Example Request:

curl https://api.zenfulfillment.com/returns/{returnId}/done -H 'Authorization: ZF-API <API-TOKEN-HERE>'

Du benötigst noch Hilfe? Kontaktiere uns Kontaktiere uns