Introduction
The GelatoConnect API enables you to programmatically integrate your systems with GelatoConnect to submit orders, track their status, and manage shipping details. This guide will help you understand how to get started with the API and implement your first integration.
Prerequisites
Before you begin working with the GelatoConnect API, you should have:
Your API key and secret (provided when setting up a connector for your customer)
Basic understanding of REST APIs and HTTP methods
Familiarity with JSON data format
A development environment capable of making HTTP requests
API Basics
The GelatoConnect Order Management API is organized around REST principles and uses standard HTTP methods to interact with resources. All API requests must use HTTPS, and all responses are returned in JSON format, including error messages.
Base URL
The base URL for the GelatoConnect API is:
https://api.partner-connect.io/api/{partner-prefix}/Your specific partner prefix will be provided during onboarding.
Authentication
All API requests must include your authentication credentials in the header. To authenticate:
Add the
X-API-KEYheader to your requestSet the value to your key and secret in the format
key:secret
Example:
X-API-KEY: your-api-key:your-api-secret
Making Your First API Request
Let's walk through the process of making a simple API request to submit an order.
1. Prepare Your Order Data
Create a JSON object with the order details. Here's a minimal example:
{
"orderReferenceId": "your-order-ref-123",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"country": "US",
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Main St",
"city": "New York",
"postCode": "10001",
"state": "NY",
"email": "[email protected]",
"phone": "1234567890"
},
"items": [
{
"itemReferenceId": "item-123",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/path/to/printfile.pdf"
}
]
}
]
}
2. Submit the Order
Make a POST request to the submit order endpoint:
POST https://api.partner-connect.io/api/{partner-prefix}/orderInclude your authentication header and the JSON order data in the request body.
3. Handle the Response
If successful, you'll receive a response like this:
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "your-order-ref-123",
"createdAt": "2025-04-12T10:23:28+00:00"
}The id field contains the GelatoConnect order ID, which you should store for future reference.
Common API Operations
Once you're comfortable with basic order submission, you can explore other API operations:
Get Order Details
Retrieve information about an existing order:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Cancel an Order
Cancel an order that hasn't been shipped:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancel
Search Orders
Find orders based on specific criteria:
POST https://api.partner-connect.io/api/{partner-prefix}/search
Update Shipping
Modify shipping details for an order:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Implementing Customer Products
Instead of using Product UIDs, you can use Customer Products for a more human-readable approach:
{
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
}
}This requires setting up Customer Products in GelatoConnect before using them in API calls.
Testing Your Integration
Before going live with your integration, thoroughly test it using these approaches:
Test with Sample Orders: Create test orders with low quantities and validate they appear correctly in GelatoConnect.
Verify Order Status Updates: Track orders through their lifecycle to ensure your system receives and handles status changes correctly.
Error Handling: Intentionally create invalid orders to test your error handling logic.
End-to-End Testing: Complete the entire order flow from submission to delivery with a small set of test orders.
Best Practices
To ensure optimal integration with the GelatoConnect API:
Store Order IDs: Always store the GelatoConnect order ID returned in the order creation response.
Implement Error Handling: Add robust error handling to manage unexpected responses or API downtime.
Use Idempotency: Generate unique order reference IDs to avoid duplicate orders.
Implement Exponential Backoff: When receiving rate limit errors (429), use increasing wait times between retries.
Monitor API Usage: Keep track of your API usage to avoid hitting rate limits.
Troubleshooting Common Issues
Authentication Errors
If you receive a 401 Unauthorized error, check that:
Your API key and secret are correct
The format is
key:secretin the X-API-KEY headerYou're using HTTPS, not HTTP
Invalid Request Errors
If you receive a 400 Bad Request error:
Check the error message for specific field issues
Verify all required fields are included
Confirm the JSON format is valid
Rate Limit Errors
If you receive a 429 Too Many Requests error:
Implement a backoff strategy to space out requests
Consider batching requests where possible
Review your integration for unnecessary repeated calls
Next Steps
Now that you understand the basics of the GelatoConnect API, you're ready to:
Read the full API documentation for detailed endpoint information
Learn about API best practices for authentication, rate limits, and error handling
Explore working with API endpoints for detailed operation examples
For additional support with your API integration, contact our support team at [email protected].