How to place your first Peecho print API order

Using the Peecho print API to place an order

The process starts when your customer completes a purchase on your app or platform. You collect the payment using your own checkout system. By integrating the Peecho print API into your order flow, you automate order creation, payment and submission to production.

The API also lets you request quotes, update order details, track statuses and more.

Using Peecho’s hosted checkout to place an order

To use Peecho’s hosted checkout, start by creating a product listing in your dashboard. This generates a checkout link, which you can share with customers directly or embed on your website as a 'Buy Print' button.

To place an order using our API v3, follow these steps:

1. Get your API key and add account details
2. Choose a product
3. Create a file
4. Create an order
5. Submit payment

We'll walk through each of these steps using a hardcover book as an example.

1. Get your API key and add account details

First, create an account in the test environment to obtain your API credentials. You can find your API key in the test dashboard under Settings > API.

Keep in mind that productIds and apiKeys from the production environment do not work in the test environment, and vice versa.

Before placing an order, you need to enter your business address. This is important because the tax applied to each order is partly based on your company's location.

For testing, you can use mock data. To add your details, go to Dashboard > Settings > API > Company details.

2. Choose a product

For this example, we’ll use one of our most popular products: an A4 landscape hardcover book (21 x 29.7 cm).

Each account has a unique set of product IDs. To find yours, go to Dashboard > Settings > Products > Books > Product ID.

If you want to test the API with a different product, you can find and select it on the same page. Just make sure you have a file that meets the product’s specifications.

3. Create a file

Each product requires a specific file setup. Most products recommend a resolution of 300 DPI and must be submitted in the RGB color profile. For detailed file guidelines, visit the Peecho Help Center.

For this example, we’re using the A4 landscape photobook, which measures 21 x 29.7 cm. This product requires a minimum of 24 pages, so your file must be at least that length.

The Peecho API accepts two file setups for books:

a) Cover and content in the same file

Create a single PDF containing the front cover, content pages and back cover, arranged as single pages in that order. The first page will be printed as the front cover, and the last as the back cover. By default, the spine is left blank.

If you want to include a spine, there are two options:

1. Dynamic spine – Generated automatically by Peecho, based on the product dimensions and the dynamic_spine_details object in your create new order api call
2. Custom spine – Supplied by you via a custom PDF URL linked in the spine_details object. Use the Get spine width endpoint to calculate the correct spine width.

b) Cover and content as separate files

In this setup, you provide two files:

• One for the cover (including front cover, spine and back cover as a single spread)
• One for the inner pages (content only)

This approach is ideal for wraparound cover designs. If you use this setup, you’ll need to manually calculate the spine width using the Get spine width endpoint.

If you don’t have a file to test with, you can use the Peecho sample file, which includes both cover and content. If you want to test a custom spine with the sample file, you can use the custom spine PDF file.

4. Create an order

Now that you’ve selected a product and prepared your file, you can create the order by sending a POST request to:
https://test.www.peecho.com/rest/v3/orders/

Creating an order requires a single API call, including all relevant details. Make sure to use the MerchantKey and productId from your test account — production credentials won’t work in the test environment.

You can create an order in two ways:

a) Include the file when creating the order

Specify the file URL in the file_details object.

b) Add the file after payment

Leave the file_details parameters blank during order creation. You’ll provide the files later using the Set files asynchronously endpoint.

Once the order is created, it appears in your dashboard in the Open state. You’ll need the orderId to make a payment and submit the order to production as part of the order flow.

For this example, we’ll create an order with two items — one with a dynamic spine and one with a custom spine URL. The data should follow the format of the Order object:

{
  "merchant_api_key": "YourAPIKeyHere:ABCD1234XXXX",
  "purchase_order": "",
  "currency": "EUR",
  "item_details":
  [
    {
      "item_reference": "hardcover_22",
      "offering_id": "YourOfferingIDHere",
      "quantity": 3,
      "file_details":
      {
        "content_url": "https://peecho-thumbnailer.s3.eu-west-1.amazonaws.com/Peecho+HCB+print+file.pdf",
        "content_width": 210,
        "content_height": 29.7,
        "number_of_pages": 80,
        "spine_details":
        {
          "dynamic_spine_details":
          {
            "text_font": "Arial",
            "text_size": 10,
            "text_colour": "#77493f",
            "text_top": "top text",
            "text_center": "center text",
            "text_bottom": "bottom text"
          }
        }
      }
    },
    {
      "item_reference": "hardcover_23",
      "offering_id": 233309,
      "quantity": 2,
      "file_details":
      {
        "content_url": "https://peecho-thumbnailer.s3.eu-west-1.amazonaws.com/Peecho+HCB+print+file.pdf",
        "content_width": 210,
        "content_height": 29.7,
        "number_of_pages": 80,
        "spine_details":
        {
          "custom_spine_url": "https://peecho-thumbnailer.s3.eu-west-1.amazonaws.com/Custom%20spine%20PDF.pdf"
        }
      }
    }
  ],
  "address_details":
  {
    "email_address": "joshua@designy.com",
    "shipping_address":
    {
      "first_name": "Joshua",
      "last_name": "Grim",
      "address_line_1": "Test",
      "address_line_2": 1,
      "zip_code": "35100",
      "city": "Florida",
      "state": null,
      "country_code": "ARE"
    }
  }
}

‍

5. Submit payment

To pay for a print API order, send a request to the Payment endpoint. Before you can do this, you'll need to buy credits in the test environment. These credits are used to pay for the orders you create.

To purchase credits, go to Dashboard > Settings > API > Credit > Buy credit. In the test environment, you can use mock payment methods such as Stripe test cards.

Once you’ve acquired credits, call the Payment endpoint to confirm that the order is finalized and ready for production. This simulates a scenario where your customer has already paid you directly.

To submit the payment, you’ll need the following:

• orderId
• Test merchant_api_key
• secret (SHA-256 encoded)

The Peecho API also includes endpoints for order quotations, product information and order status.

For full details, explore our API documentation. If you need help testing or implementing API v3, we’re happy to assist – just reach out to us at support@peecho.com.