This guide provides practical instructions and examples for working with GelatoConnect's Order API endpoints. We'll cover how to submit orders, cancel orders, update shipping information, retrieve order details, and search for orders using the API.
Prerequisites
Before working with these endpoints, ensure you have:
Your API key and secret (provided when setting up a connector for your customer)
The base URL for your API endpoints
Basic understanding of making HTTP requests with curl or your preferred tool
Submit Order
The Submit Order endpoint allows you to create a new order in GelatoConnect.
Endpoint: POST /{submitOrderUrl}
Request Example
# Basic order submission
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "YOUR-ORDER-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": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"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/files/printfile.pdf"
}
]
}
]
}'
Response Example
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "YOUR-ORDER-123",
"createdAt": "2025-04-13T10:23:28+00:00"
}Using Customer Products
Instead of specifying a productUid, you can use customer products with productName and productVariant:
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "YOUR-ORDER-124",
"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": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
},
"quantity": 100,
"files": [
{
"type": "front",
"url": "https://example.com/files/front.pdf"
},
{
"type": "back",
"url": "https://example.com/files/back.pdf"
}
]
}
]
}'International Orders
For international orders, provide retail prices for customs declarations:
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "INTL-ORDER-456",
"orderType": "order",
"currency": "EUR",
"retailCurrency": "GBP",
"retailShippingPriceInclVat": 6.99,
"shippingAddress": {
"country": "DE",
"firstName": "Hans",
"lastName": "Schmidt",
"addressLine1": "Unter den Linden 10",
"city": "Berlin",
"postCode": "10117",
"email": "[email protected]",
"phone": "+49123456789"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"retailPriceInclVat": 19.99,
"files": [
{
"type": "default",
"url": "https://example.com/files/printfile.pdf"
}
]
}
]
}'Common Issues
Missing Required Fields: Ensure all required fields are included in your request.
Invalid File URLs: Make sure your file URLs are publicly accessible.
Unknown Product UID: Verify that the product UID exists or use customer products.
Duplicate Order Reference ID: Use unique order reference IDs for each order.
Cancel Order
The Cancel Order endpoint allows you to stop the production and shipment process for an order that hasn't been shipped yet.
Endpoint: POST /{orderCancelUrl}/{orderId}/cancel
Request Example
# Cancel using Gelato Order ID
curl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \
--header 'X-API-KEY: your-key:your-secret'
# Cancel using your Order Reference ID
curl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \
--header 'X-API-KEY: your-key:your-secret'
Response Example
{
"code": 200,
"message": "OK"
}Common Issues
Order Already Shipped: Orders that have already been shipped cannot be cancelled.
Order Not Found: Verify that the order ID or reference ID is correct.
Authentication Issues: Ensure your API key and secret are correct.
Update Shipment
The Update Shipment endpoint allows you to modify the shipping method or update the shipping address for an order that hasn't been shipped yet.
Endpoint: POST /{updateShipmentURL}/{orderId}
Request Example
# Update shipping details
curl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"shipmentMethodUid": "fed_ex_2_day",
"shippingAddress": {
"country": "US",
"firstName": "Jane",
"lastName": "Smith",
"addressLine1": "456 Park Ave",
"city": "New York",
"postCode": "10022",
"state": "NY",
"email": "[email protected]",
"phone": "987-654-3210"
}
}'
# Update only shipping method
curl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"shipmentMethodUid": "fed_ex_2_day"
}'
Response Example
{
"shippingAddress": {
"id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1",
"orderId": "32884a3e-bd09-42be-8225-c5cea7d24611",
"country": "US",
"firstName": "Jane",
"lastName": "Smith",
"addressLine1": "456 Park Ave",
"city": "New York",
"postCode": "10022",
"state": "NY",
"email": "[email protected]",
"phone": "987-654-3210"
},
"shipment": {
"shipmentMethodUid": "fed_ex_2_day",
"shipmentMethodName": "FedEx 2Day",
"fulfillmentCountry": "US",
"fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa",
"packageCount": 1,
"initialMinDeliveryDate": "2025-04-15",
"initialMaxDeliveryDate": "2025-04-15",
"serviceType": "normal"
}
}Common Issues
Order Already Shipped: Shipping details for shipped orders cannot be updated.
Missing Required Fields: Ensure all required fields are included in the shipping address.
Invalid Shipping Method: Verify that the shipping method UID is valid.
Order Not Found: Check that the order ID or reference ID is correct.
Get Order
The Get Order endpoint allows you to retrieve detailed information about an existing order.
Endpoint: POST /{getOrderURL}/{orderId}
Request Example
# Get order using Gelato Order ID
curl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'X-API-KEY: your-key:your-secret'
# Get order using your Order Reference ID
curl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \
--header 'X-API-KEY: your-key:your-secret'
Response Example
The response includes detailed information about the order, including:
Order details (ID, reference, status, timestamps)
Shipping address
Items ordered
Shipment information
Financial information
Due to the length of the response, refer to the API documentation for the complete response structure.
Using the Response Data
The Get Order response provides valuable information that you can use to:
Display Order Status: Show customers the current status of their orders.
Track Shipments: Extract tracking information for shipment tracking.
Verify Order Details: Confirm that order details are correct.
Analyze Order History: Build reporting and analytics based on order data.
Common Issues
Order Not Found: Verify that the order ID or reference ID is correct.
Authentication Issues: Ensure your API key and secret are correct.
Search Orders
The Search Orders endpoint allows you to retrieve a list of orders based on specific criteria.
Endpoint: POST /{searchOrdersURL}
Request Example
# Search by fulfillment status
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"fulfillmentStatus": ["shipped", "delivered"]
}'
# Search by date range
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"startDate": "2025-01-01T00:00:00+00:00",
"endDate": "2025-04-13T23:59:59+00:00"
}'
# Search by order reference ID
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "YOUR-ORDER-123"
}'
# Search with pagination
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"fulfillmentStatus": ["created", "printed"],
"limit": 50,
"offset": 0
}'
Response Example
{
"orders": [
{
"id": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
"clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
"orderReferenceId": "YOUR-ORDER-123",
"fulfillmentStatus": "shipped",
"financialStatus": "paid",
"currency": "USD",
"totalInclVat": "33.45",
"orderType": "order",
"channel": "api",
"firstName": "John",
"lastName": "Doe",
"country": "US",
"itemsCount": 1,
"createdAt": "2025-04-10T11:05:09+00:00",
"updatedAt": "2025-04-10T14:05:10+00:00",
"orderedAt": "2025-04-10T11:05:07+00:00",
"customerReferenceId": "CUST-456"
},
// More orders...
]
}Pagination
The Search Orders endpoint supports pagination to manage large result sets:
# First page (50 items)
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"fulfillmentStatus": ["shipped"],
"limit": 50,
"offset": 0
}'
# Second page (next 50 items)
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"fulfillmentStatus": ["shipped"],
"limit": 50,
"offset": 50
}'
Common Search Scenarios
Orders by Status:
{ "fulfillmentStatus": ["created", "printed"] }Orders by Date Range:
{
"startDate": "2025-04-01T00:00:00+00:00",
"endDate": "2025-04-13T23:59:59+00:00"
}Orders by Country:
{ "countries": ["US", "CA"] }Combining Criteria:
{
"fulfillmentStatus": ["shipped"],
"countries": ["US"],
"startDate": "2025-04-01T00:00:00+00:00"
}
Common Issues
No Results: Check that your search criteria are not too restrictive.
Too Many Results: Use pagination and/or additional filters to narrow your search.
Invalid Format: Ensure date formats follow ISO 8601 (YYYY-MM-DDTHH:MM:SS+00:00).
Linking Templates to API Endpoints
When submitting orders via API, you'll often need to transform data between your format and GelatoConnect's format. Templates handle this transformation, but you must explicitly link your template to the API endpoint for it to be applied.
How to link a template to an order submit endpoint:
Navigate to your connector list and click the Edit hyperlink next to the submit order endpoint.
On the endpoint configuration page, locate the Endpoint template section
Select your order submit template from the dropdown menu
Click the Set endpoint button in the top right of the page
Click Save changes in the top right to apply your configuration
After completing these steps, all order submissions sent to this endpoint will use your template to transform the data before processing. This ensures your system's format is correctly converted to GelatoConnect's expected format.
Without this configuration, your template will not be applied even if it exists and is correctly designed, which can lead to order validation failures if your data format doesn't exactly match GelatoConnect's requirements.
Integration Best Practices
When integrating with the Order API endpoints, consider these best practices:
1. Store Order IDs
Always store both your order reference ID and the Gelato order ID returned in the response. This makes it easier to track and reference orders in both systems.
2. Handle Errors Gracefully
Implement proper error handling for each API call. Parse the error message from the response to provide meaningful feedback to users and implement appropriate recovery mechanisms.
For guidance on implementing robust error handling, refer to the "Error Handling Best Practices" section in the Order Management API Documentation.
3. Implement Idempotency
Generate unique order reference IDs for each order to prevent duplicate submissions due to network issues or retries.
4. Use Webhook Notifications
Instead of polling for order status updates, set up webhook notifications to receive real-time updates when order statuses change.
5. Validate Data Before Submission
Validate order data on your end before sending it to the API to catch obvious errors and improve user experience.
6. Implement Retry Logic
Add retry logic with exponential backoff for transient errors, particularly for rate limit (429) responses.
For implementation details on exponential backoff and jitter, refer to the "Rate Limit Best Practices" section in the Order Management API Documentation or the AWS blog post on exponential backoff and jitter.
7. Optimize Search Queries
Be specific with search criteria to minimize result set size and improve performance.
8. Cache Reference Data
Cache product UIDs and other reference data to reduce the number of API calls needed.
Conclusion
The GelatoConnect Order API provides a powerful set of endpoints for managing the entire order lifecycle. By understanding how to effectively use these endpoints, you can create a seamless integration between your systems and GelatoConnect.
For more detailed information, refer to the Order Management API Documentation and contact our support team at [email protected] if you have any questions.