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/update. CSV row with Reference already existing in the integration will update the order, while if the Reference doesn't exist, an order will be created in the integration. CSV file containing errors for some orders would still create/update the orders with valid data. This API will return a HTTP response status code 200 if all the orders provided in the csv are successfully update or created, if not, it returns a HTTP response 202 Accepted with the errors.

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:

This endpoint returns response 200 or 202. If all orders in the CSV are processed successfully the response has the following structure

{
  "message": "Import CSV succeeded",
  "errors": [],
  "orders": [
    {
      "reference": 1991,
      "shipping_option": "GLS",
      "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",
      ...
    }
  ]
}<br>

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:

{
  "message": "Import CSV succeeded partially, please check the errors",
  "errors": [
    {
      "reference": 1990,
      "error": [
        "SKU is missing, check the value in your CSV"
      ]
    }
  ],
  "orders": [
    {
      "reference": 1991,
      "shipping_option": "GLS",
      "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;;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

This CSV API Cancels the orders provided with ZF references in a CSV File. This will cancel only those orders which could be cancelled, while it will return errors for those which cannot be cancelled. This API will return a HTTP response status code 200 if all the orders provided in the csv are successfully cancelled, if not, it returns a HTTP response 202 Accepted with the errors.

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>'

CSV API Documentation

Authentication

POST /orders/import

GET /orders/export

GET /orders/external/{reference}

POST /orders/cancel

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

POST /products/import

GET /products/export

POST /inventory_shipments/import

PUT /inventory_shipments/{reference}/import

GET /inventory_shipments/export

GET /inventory_shipments/export/{reference}/reference

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

GET /returns/export

Search returns

POST /returns/{returnId}/done

CSV Columns:

Reference - the ZF order reference is a mandatory parameter