Orders API

1. Overview

The Zakeke Orders API is a comprehensive collection of endpoints designed to facilitate the seamless management of orders within the Zakeke ecosystem. This robust set of APIs encompasses retrieval functions for accessing order information as well as registration capabilities for the integration and synchronization of orders within your platform.

2. List of endpoints

The following are the enpoints available for the Orders API.

Please Note

All the endpoints have the following base url: https://api.zakeke.com/

warning

All API calls need to be authenticated and authorized via an S2S-type oAuth token. For all the details see the Authentication and Authorization section.

Method	Endpoint	Description
GET	`/v2/orders`	All orders for customized products placed by customers.
GET	`/v2/order/{orderCode}`	Retrieve an order given its code.
GET	`/v2/orders/{order}`	Retrieve an order given its ID in Zakeke.
POST	`/v2/order`	Register an order.

In the following sections we will provide details of each endpoint with a description of the information they provide and the operations they follow.

3. Error codes

In RESTful API calls, such as those made to Zakeke, HTTP status codes are crucial for indicating the outcome of API requests. Codes in the 2xx range signify successful operations, 4xx errors denote client-side issues, and 5xx errors indicate server-side problems. This system allows developers to quickly identify and address issues with API interactions, enhancing the efficiency of integrating with Zakeke's services.

For certain status codes, Zakeke includes an error message in the response body to elucidate the cause of the error. This is particularly useful when a single status code, like 404 Not Found or 400 Bad Request, could indicate various issues. These messages help developers pinpoint the specific problem, facilitating a more efficient troubleshooting process when integrating with Zakeke's APIs.

4. Retrieve all orders

This endpoint returns all orders placed by customers, from newest to oldest.

Request

GET https://api.zakeke.com/v2/orders

For the endpoint it is possible to specify parameters to perform pagination of the result. Pagination of the result is particularly important to obtain optimal performance in the presence of a large number of orders.

warning

Use pagination parameters and an optimal page size (maximum 100 items per page) to maintain good performance when running the API.

The following are the parameters you can use in query string for pagination:

Parameter	Data type	Description
pageSize	`integer`	The page size of the result.
pageNumber	`integer`	The number of the page to return. The first page will have `pageNumber` = 1

Response

The API call returns a JSON with the following structure:

[
  {
    "id": 0,
    "code": "string",
    "orderNumber": "string",
    "salesChannel": {
      "id": 0,
      "url": "string",
      "platform": "string"
    },
    "items": [
      {
        "code": "string",
        "productSku": "string",
        "productName": "string",
        "productTemplateId": "string",
        "thumbnail": "string",
        "quantity": 0,
        "design": "string",
        "preDesignedTemplateName": "string",
        "printFilesStatus": "string",
        "printingFilesZip": "string",
        "printingFiles": [
          {
            "type": "string",
            "url": "string"
          }
        ],
        "price": {
          "value": 0,
          "currency": "string"
        }
      }
    ],
    "orderDate": "string"
  }
]

Each item of the array in the JSON result is an object that represents an order and whose properties have the following meaning:

Parameter	Data type	Description
id	`integer`	Unique identifier generated by Zakeke for the order.
code	`string`	Identification code assigned by the merchant to the order.
orderNumber	`string`	Identification code assigned by the ecommerce to the order.
salesChannel	`object`	Object that reports the data of the sales channel on which the order has been executed, if any.
items	`array`	Details on customized products ordered.
orderDate	`string`	Date and time the order has been placed.

Sales Channels allows you to connect and manage multiple commerce channels to your Zakeke account. Sales channels are the different platforms where you sell your customizable products, such as Shopify, WooCommerce, Etsy, etc.. This feature allows you to share all customizable products, including the ones with variants, among several platforms and manage all your orders and stores from a single Zakeke account instead of creating a separate account for each platform. If the order has been placed on a sales channel, for that sales channel the salesChannel property will be an object with the following structure:

{
  "id": 0,
  "url": "https://....",
  "platform": "string"
}

where:

Parameter	Data type	Description
id	`integer`	Numeric code that uniquely identifies the sales channel within Zakeke.
url	`string`	URL to the sales channel web site.
platform	`string`	The ecommerce platform for the sales channel (Shopify, WooCommerce, etc.)

For each custom product ordered, the items property array will contain an object with the following structure:

{
  "code": "string",
  "productSku": "string",
  "productName": "string",
  "productTemplateId": "string",
  "thumbnail": "string",
  "quantity": 0,
  "design": "string",
  "preDesignedTemplateName": "string",
  "printFilesStatus": "string",
  "printingFilesZip": "string",
  "printingFiles": [
    {
      "type": "string",
      "url": "string"
    }
  ],
  "price": {
    "value": 0,
    "currency": "string"
  }
}

where:

Parameter	Data type	Description
code	`string`	Order detail identification code assigned by the ecommerce.
productSku	`string`	The SKU code that identifies the customized product in ecommerce.
productName	`string`	The customized product name.
productTemplateId	`string`	Code that identifies the product in the POD (Print on demand) system from which it derives, if any
thumbnail	`string`	A preview image URL of the customized product.
quantity	`integer`	The number of products ordered.
design	`string`	The design id for the customized product.
preDesignedTemplateName	`string`	If the product has been customized starting from a pre-designed template, reports the name of the pre-designed template used.
printFilesStatus	`string`	The status of the print-ready file production process. It can be: INPROCESS or READY.
printingFilesZip	`string`	After the print-ready files are generated, it will report the URL of the zip file containing all the files.
printingFiles	`array`	After the print-ready files are generated, it will contain the list of all the files, with the type (SVG, PNG, PDF, etc.) and URL for each of them.
price	`object`	The total amount of the order and the currency in which it is expressed.

Furthermore, in the case of using pagination parameters (strongly recommended), the response also returns the following two custom headers:

Parameter	Data type	Description
X-Total-Count	`integer`	The total number of orders.
X-Has-More-Pages	`boolean`	There is a page following the current one.

Naturally, HTTP headers have textual content but they can be interpreted in the indicated data type.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the order list.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.

Examples

Example 1 Get the first 20 orders.

curl -X GET https://api.zakeke.com/v2/orders?pageSize=20&pageNumber=1 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

The response will have the body with the first 20 orders and the following custom headers:

X-Total-Count: "71" X-Has-More-Pages: "True"

5. Retrieve an order by code

This endpoint allows you to obtain the details of an order starting from its code. By code we mean the unique identifier that allows the merchant to find the order in their ecommerce system.

Request

GET https://api.zakeke.com/v2/order/{orderCode}

The orderCode parameter is the order identifier used by the merchant to find an order on the ecommerce.

Response

The response provides a JSON object representing the order having the code specified in the request, if it exists. The object will have the exact same structure as a single array item returned in response to the call to get all orders.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested order.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No order was found with the code that matches the request.

6. Retrieve an order by ID

This endpoint allows you to obtain the details of an order starting from its ID in Zakeke.

Request

GET https://api.zakeke.com/v2/orders/{orderID}

The orderID parameter is the unique identifier generated by Zakeke for the order.

Response

The response provides a JSON object representing the order having the ID specified in the request, if it exists. The object will have the exact same structure as a single array item returned in response to the call to get all orders.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested order.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No order was found with the ID that matches the request.

7. Register an order

This endpoint allows you to register an order in Zakeke.

Request

POST http://api.zakeke.com/v2/order

The API call expects a JSON with the following structure in the body:

{
  "orderCode": "string",
  "orderDate": "2023-11-03T09:13:38.437Z",
  "sessionID": "string",
  "total": 0,
  "details": [
    {
      "orderDetailCode": "string",
      "sku": "string",
      "designID": "string",
      "modelUnitPrice": 0,
      "designUnitPrice": 0,
      "quantity": 0,
      "designModificationID": "string"
    }
  ],
  "compositionDetails": [
    {
      "orderDetailCode": "string",
      "composition": "string",
      "unitPrice": 0,
      "quantity": 0
    }
  ]
}

where:

Property	Data type	Description
orderCode	`string`	Unique identifier of the order on the e-commerce.
orderDate	`string`	Order date in ISO 8601 format.
sessionID	`string`	The e-commerce session identifier.
total	`money`	The total order amount.
details	`array`	List of customized product details.
compositionDetails	`array`	Lsit of configured product details.

For each of the customized product ordered, the object in the details array has the following structure:

{
    "orderDetailCode": "string",
    "sku": "string",
    "designID": "string",
    "modelUnitPrice": 0,
    "designUnitPrice": 0,
    "quantity": 0,
    "designModificationID": "string"
}

where:

Property	Data type	Description
orderDetailCode	`string`	The ID on your system for the line item.
sku	`string`	Unique identifier that the ordered product has in ecommerce.
designID	`string`	Unique design identifier provided by Zakeke.
modelUnitPrice	`money`	Product unit price without the design price.
designUnitPrice	`money`	Unit price applied to customization.
quantity	`integer`	Quantity of products ordered.
designModificationID	`string`	Identifier assigned by Zakeke for the particular instance of fields values in the case of an order with the Names and Numbers tool or for the bulk purchase with a different print file for each ordered variations

For each of the configured product ordered, the object in the compositionDetails array has the following structure:

{
  "orderDetailCode": "string",
  "composition": "string",
  "unitPrice": 0,
  "quantity": 0
}

where:

Property	Data type	Description
orderDetailCode	`string`	The ID on your system for the line item.
composition	`string`	The product configuration identifier for the product that the line item belongs to.
unitPrice	`money`	The unit price of the product, including the configuration price, after discounts have been applied. Must be in the base currency set in the Zakeke API settings.
quantity	`integer`	The number of products that were purchased.

Orders API

1. Overview​

2. List of endpoints​

3. Error codes​

4. Retrieve all orders​

Request​

Response​

HTTP Response Codes​

Examples​

5. Retrieve an order by code​

Request​

Response​

HTTP Response Codes​

6. Retrieve an order by ID​

Request​

Response​

HTTP Response Codes​

7. Register an order​

Request​

1. Overview

2. List of endpoints

3. Error codes

4. Retrieve all orders

Request

Response

HTTP Response Codes

Examples

5. Retrieve an order by code

Request

Response

HTTP Response Codes

6. Retrieve an order by ID

Request

Response

HTTP Response Codes

7. Register an order

Request