How to Place an Order Using a Customer Product
This guide will walk you through the process of placing an order using a Customer Product via the GelatoConnect API. Customer Products allow you to use your own product configurations when placing orders, simplifying the order process and ensuring consistency with your internal product definitions.
API Endpoint
POST https://order.ie.live.gelato.tech/api/v4/orders
Request Structure
The key elements for using a Customer Product in your order are the productName and productVariant fields within the items array. Here's an example request structure:
{
"clientId": "your-client-id",
"orderReferenceId": "your-order-reference",
"customerReferenceId": "your-customer-reference",
"orderType": "order",
"currency": "USD",
"retailCurrency": "USD",
"retailShippingPriceInclVat": 5.99,
"shippingAddress": {
"country": "US",
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Main St",
"city": "Anytown",
"postCode": "12345",
"state": "CA",
"email": "[email protected]",
"phone": "1234567890"
},
"items": [
{
"itemReferenceId": "your-item-reference",
"productName": "sample for order intake",
"productVariant": {
"paper": "a1",
"color": "front"
},
"files": [
{
"type": "default",
"url": "https://example.com/your-file.pdf"
}
],
"quantity": 1,
"retailPriceInclVat": 79.99
}
]
}
Key Fields for Customer Products
When using a Customer Product, pay special attention to these fields in the items array:
productName: This should match the name of your Customer Product as defined in GelatoConnect.
productVariant: This object contains the specific options for your product. The keys and values should match the variant options you've set up for your Customer Product.
In the example above:
"productName": "sample for order intake",
"productVariant": {
"paper": "a1",
"color": "front"
}
This configuration tells GelatoConnect to use the Customer Product named "sample for order intake" with the specified paper and color options.
Important Notes
When using a Customer Product, you don't need to provide a
productUidfor the item. TheproductNameandproductVariantfields are used instead to determine the exact product configuration.Ensure that the
productNameexactly matches the name of your Customer Product in GelatoConnect.The
productVariantobject should only include options that you've defined for your Customer Product. Including undefined options will result in an error.The rest of the order request structure remains the same as a standard order. You can include multiple items, each using a different Customer Product if needed.
Always ensure that the files you provide match the requirements of your Customer Product configuration.
Response
After successfully placing an order, you'll receive a response that includes details about the order, including an order ID, fulfillment status, and more. Always check the response to ensure your order was processed correctly.
Troubleshooting
If you encounter issues when placing an order with a Customer Product, check the following:
Verify that the
productNameexactly matches your Customer Product name.Ensure all required
productVariantoptions are provided and match your Customer Product configuration.Check that the provided files meet the requirements of your Customer Product.
Verify that your API credentials are correct and that you have permission to use the specified Customer Product.
For any persistent issues, contact GelatoConnect support for assistance.