# 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](https://api-docs.burgerprints.com/). 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
2. Create a new request 3. In the **Headers** tab, fill: 'api-key' and api key of store channel respectively to the Key and Value column
4. Click on "**Send**" button If authorized, you should receive a JSON response with code: 200 If 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: 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/123`For 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 2. #### 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 history** Orders 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. 3. #### 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** 4. #### 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 | 5. #### 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:
EventDescription
Order createdWhen an order is created via API, import csv, sync from connected store
Order cancelledWhen an order is cancelled
Order updatedWhen an order requires an information update
Order paidWhen an order is paid
Order processedWhen an order enters the production process
Order sent for printingWhen an order is sent to fulfillment facility for printing
Tracking number added to a package of an orderWhen 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.burgerprints.com/integrations-and-store-connections/integrations/how-to-use-the-api-and-developer-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.