How to use the API and developer guide

Overview

This article explains how to access BurgerPrints services through the BurgerPrints API. It is intended to help sellers build automated workflows between their stores and the BurgerPrints fulfillment system.

Understanding API Setup And Usage

API Connection and setup

Firstly, make sure you understand our API documentation here. To get the API key, access the Stores module and click on the "Get API key" button of the fulfillment store that you want. Make sure you save the API key securely.

BurgerPrints uses an API key-based authentication. To authenticate your requests, you must include your private API key in the request headers. This key acts like a password and grants full access to your account’s API features.

Testing your API

Use Postman to verify your API key and test requests before integrating into your application. To verify your API connection:

1. Access the BurgerPrints API documentation and click on the "Run in Postman" button

1. Create a new request

2. In the Headers tab, fill: 'api-key' and api key of store channel respectively to the Key and Value column

1. Click on "Send" button

If authorized, you should receive a JSON response with code: 200If you get an authentication error, check:

• Header name spelling

• API key value

• That you’re using Headers and not query params

Requests and responses

API endpoint

All BurgerPrints API requests must be sent to the following base URL:https://api.burgerprints.com/If your system uses a proxy, ensure that every request includes the HTTP header: api.burgerprints.com

Request structure

Some required parameters (such as object identifiers) must be provided directly in the request path. Example: GET /order/123For POST and PUT requests, more complex data can be submitted in the request body as JSON-encoded data. Example:POST /order{"shipping_name":{...},"shipping_city":[...]}

Response structure

All API responses are returned as JSON objects that contain a response status code (identical to the HTTP status code) and the result of the action. If the status code is 200, then the action was successful. Example:

{
   "code": 200, //Response status code
   "result":{
      //API method return data
      //...
   }
}

Error response

If a request fails, the HTTP status code will fall outside the 2xx range, and the response body will include error details. Example:

{
    "is_success": false,
    "message": "Failed to authenticate.",
    "errors": []
}

In general, response codes in the 4xx range indicate an error that resulted from Client-side (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate a Server-side error within BurgerPrints's system.

Core Workflow Overview

Below is the standard sequence of actions you will follow when integrating with the API.

1. Preparing products for ordering

Before creating an order, you must ensure your product data is ready. Each order line item must include:

• The valid SKU of an item’s variant from the catalog

• Design file URLs

• Quantity of the item

The API will validate that the SKU and print files are usable

1. Create order via API

Once product data is prepared, you can submit an order.BurgerPrints validates the following information during order creation:

• Recipient information

• Shipping address format

• Product line items

• Shipping method

• IOSS information

• SKU availability

• Print file accessibility

What happens after submission

• The API returns an order ID

• The order appears in the BurgerPrints dashboard

• Initial status is either Unpaid or Incomplete, depending on if the order’s information is complete or incomplete

Monitoring with import historyOrders submitted via the API can be viewed in the Import sub-menu of the Logs menu. API-created orders are grouped by type and include timestamps, status, and system messages. Click on an order record to view item details and messages.

How do I debug a failed request? Follow these steps in order:

• Step 1: Verify that all required fields are included and valid, and confirm that the API key and target environment are correct.

• Step 2: Review all error messages and response details returned by the API, as well as the corresponding entries in the BurgerPrints logs.

• Step 3: If an order ID is returned but the order is not displayed, use the order ID to call get order details API to confirm whether the order was created or not.

• Step 4: If the issue persists after these checks, contact BurgerPrints support and provide the request reference, order ID (if available), and relevant error messages so the technical team can investigate further.

1. Order payment

BurgerPrints validates the following information during order payment:

• The validity of the ID of the Order to be charged

• Account’s balance

If successful:

• The order’s status changes to Paid if order id is valid and account balance is sufficient

If there are issues:

• The order status remains Unpaid

1. Fulfillment & production

Once paid:

• The order enters Processed status

• Production begins at the fulfillment partner

• The order status updates automatically as it progresses

When using the API to manage orders, the following statuses are used:

Status	Description
Incompleted	Missing or invalid data
Unpaid	Order submitted, awaiting payment
Paid	Payment completed
Processed	Order in production
Fulfilled	Order fulfilled
Unfulfilled	Order unfulfilled

1. Retrieve order fulfillment information

BurgerPrints supports webhook notifications to deliver real-time fulfillment updates from the platform to your system. Instead of polling the API for updates, you can register a callback URL that BurgerPrints will notify when key fulfillment events occur. Once registered, BurgerPrints will send HTTP POST requests to your specified endpoint whenever a fulfillment event occurs. The list of events includes:

Event	Description
Order created	When an order is created via API, import csv, sync from connected store
Order cancelled	When an order is cancelled
Order updated	When an order requires an information update
Order paid	When an order is paid
Order processed	When an order enters the production process
Order sent for printing	When an order is sent to fulfillment facility for printing
Tracking number added to a package of an order	When a tracking number is added to an order
Package status updated to “In transit”	When the tracking is active or the first update is available and the order’s package is on its way to the recipient
Package status updated to “Not found/Info received”	When the tracking is not yet active. This is usually the status of orders with early tracking numbers, newly shipped orders, and those that have not yet been updated by the shipping company
Package status updated to “Out for delivery”	When the order is being prepared for delivery to the recipient
Package status updated to “Delivered”	When the order has been successfully delivered to the recipient
Package status updated to “Tracking Failed”	When the shipping carrier of the order cannot be detected
Package status updated to “Undelivered”	When the delivery to the recipient was unsuccessful
Package status updated to “Expired”	When the tracking numbers that have not had any updates for one month or have not been updated as delivered within two months
Package status updated to “Exception”	When the order that may have been damaged during transit, lost, or delayed due to exceptional issues
Package status updated to “Return”	When the order has been returned to the sender due to unsuccessful delivery attempts

Tips and best practices

• Always validate required fields, SKUs and print file URLs before order creation

• Test the full order flow before going live

Frequently Asked Questions

1. Is the API key revocable or rotatable? Once the store channel is opened, the associated API key is created and can not be disabled unless the store is deleted. One account can have multiple API keys at the same time, and creating new API keys will not disable old ones.