Submit Order
Submit an order in a single request.
POST /{submitOrderUrl}
The base URL and specific endpoint will be provided during connector setup.
Request Format
{
"orderReferenceId": "test",
"orderType": "order",
"currency": "EUR",
"retailCurrency": "GBP",
"retailShippingPriceInclVat": 6.99,
"shipmentMethodUid": "normal,standard,fed_ex_2_day",
"shippingAddress": {
"country": "SE",
"firstName": "My first name",
"lastName": "My last name",
"addressLine1": "17",
"addressLine2": "Address 1",
"city": "City",
"postCode": "11111",
"state": "",
"email": "[email protected]",
"phone": "+47222222",
"companyName": "MyCompany"
},
"items": [
{
"itemReferenceId": "test1",
"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://www.example.com/path/to/printfile.pdf"
}
]
}
]
}
Example curl request
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data-raw '{
"orderReferenceId": "test",
"orderType": "order",
"preventDuplicate": true,
"currency": "EUR",
"retailCurrency": "GBP",
"retailShippingPriceInclVat": 6.99,
"shipmentMethodUid": "normal,standard,fed_ex_2_day",
"shippingAddress": {
"country": "SE",
"firstName": "My first name",
"lastName": "My last name",
"addressLine1": "17",
"addressLine2": "Address 1",
"city": "City",
"postCode": "11111",
"state": "",
"email": "[email protected]",
"phone": "+47222222",
"companyName": "MyCompany"
},
"items": [
{
"itemReferenceId": "test1",
"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://www.example.com/path/to/printfile.pdf"
}
]
}
]
}'
Key Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
orderReferenceId | string | Required | Your internal order identifier |
orderType | string | Optional | Type of order: "order" (default) or "draft" |
currency | string | Required | Currency for the order (ISO code) |
retailCurrency | string | Optional | Currency used for retail prices (for cross-border orders) |
retailShippingPriceInclVat | number | Optional | Shipping price excluding VAT (despite the parameter name) |
shipmentMethodUid | string | Optional | Shipping method(s) to use, can be comma-separated |
shippingAddress | object | Required | Customer delivery address details |
items | array | Required | List of products to order |
preventDuplicate | boolean | Optional | When set to true, prevents creation of duplicate orders with the same orderReferenceId. If a duplicate is detected, an error response will be returned instead of creating a new order. |
packagingInstructions | array | Optional | Array of packaging instruction objects |
Item Parameters
Parameter | Type | Required | Description |
---|---|---|---|
itemReferenceId | string | Required | Your internal item identifier |
productUid | string | Required* | GelatoConnect product identifier (*Either productUid OR productName+productVariant is required) |
productName | string | Required* | Name of the customer product (*Either productUid OR productName+productVariant is required) |
productVariant | object | Required* | Variant details for the customer product (*Required when using productName) |
quantity | number | Required | Number of items to order |
retailPriceInclVat | number | Optional | Price excluding VAT (despite the parameter name) |
files | array | Required | List of print files for the product |
customTrim | object | Optional | Custom trim dimensions for the product |
File Parameters
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Required | Type of file. Find a list of options in the table below. |
url | string | Required | Publicly accessible URL to the print file |
File Types
Parameter | Description |
---|---|
default | The design is printed on the primary area of the product. For apparel, it is the front, while for folded cards, it is the cover+back pages. If you provide a multipage PDF, the number of pages should match the print areas as it will be used to print on all of them. |
front | Print the file on the front of the product. |
back | Print the file on the back of the product. |
cover | The file for a book cover |
neck-inner | Print the file on the inner neck of the apparel product. |
neck-outer | Print the file on the outer neck of the apparel product. |
sleeve-left | Print the file on the left sleeve of the apparel product. |
sleeve-right | Print the file on the right sleeve of the apparel product. |
inside | Print the file on the inner pages. |
chest-left-embroidery | Embroider the file on the left chest of the apparel product. |
chest-center-embroidery | Embroider the file on the center chest of the apparel product. |
chest-large-embroidery | Embroider the file on the front of the apparel product. |
sleeve-left-embroidery | Embroider the file on the left sleeve of the apparel product. |
sleeve-right-embroidery | Embroider the file on the right sleeve of the apparel product. |
wrist-left-embroidery | Embroider the file on the left wrist of the apparel product. |
wrist-right-embroidery | Embroider the file on the right wrist of the apparel product. |
Flexible File Types for Workflow-Enabled Products
For products that are enabled for workflow builder, you can use any custom file type names in the type
field of the files
array. This feature simplifies API integrations by removing the need to map files to predefined types.
Key points:
- You can name file types freely, such as
default_1
,default_2
,cover_front
,inside_page
, etc. - Allowed characters: letters (A–Z, a–z), numbers (0–9), underscores (_), periods (.), and hyphens (-)
- Maximum length: 100 characters
- File type uniqueness still applies - each
type
value must be unique within the samefiles
array
Example Usage:
{
"items": [
{
"productUid": "your-workflow-enabled-product-uid",
"quantity": 1,
"files": [
{
"type": "default_1",
"url": "https://your-file-url.com/file1.pdf"
},
{
"type": "default_2",
"url": "https://your-file-url.com/file2.pdf"
},
{
"type": "custom_cover",
"url": "https://your-file-url.com/cover.pdf"
}
]
}
]
}
Custom Trim Parameters
Parameter | Type | Required | Description |
---|---|---|---|
widthMm | number | Required | Trim width in millimeters (*Required when using customTrim) |
heightMm | number | Required | Trim height in millimeters (*Required when using customTrim) |
Packaging Instructions Parameters
Parameter | Type | Required | Description |
---|---|---|---|
packageItems | array | Required | Items to include in this package |
orderItemReferenceId | string | Required | Reference to the order item (must match itemReferenceId) |
quantity | number | Required | Quantity of the item in this package |
packingSlip | object | Optional | Packing slip configuration |
fileUrl | string | Required | URL to the PDF packing slip file |
GelatoConnect will download and store your packing slip PDF to ensure it remains accessible during the packaging process, even if the original URL expires.
Example Usage:
{
"orderReferenceId": "ORDER-12345",
"orderType": "order",
"currency": "USD",
"shippingAddress": {...},
"items": [...],
"packagingInstructions": [
{
"packageItems": [
{
"orderItemReferenceId": "ITEM-001",
"quantity": 1
}
],
"packingSlip": {
"fileUrl": "https://example.com/slip.pdf"
}
}
]
}
Shipping Address Parameters
Parameter | Type | Required | Description |
---|---|---|---|
country | string | Required | Two-letter country code (ISO 3166-1 alpha-2) |
firstName | string | Required | Recipient's first name |
lastName | string | Required | Recipient's last name |
addressLine1 | string | Required | First line of the street address |
addressLine2 | string | Optional | Second line of the street address |
city | string | Required | City name |
postCode | string | Required | Postal or ZIP code |
state | string | Required* | State or province code (*Required for US, CA, AU addresses) |
string | Required | Recipient's email address | |
phone | string | Required | Recipient's phone number with country code |
companyName | string | Optional | Business name (if applicable) |
isBusiness | boolean | Optional | Whether the address is for a business |
federalTaxId | string | Optional | Federal tax ID for business addresses |
stateTaxId | string | Optional | State tax ID for business addresses |
registrationState | string | Optional | State where business is registered |
Special Notes for International Orders
For international orders, provide retail product price and retail shipping price as:
retailCurrency
: Currency which retail prices are provided inretailShippingPriceInclVat
: Shipping price excluding VAT (ignore the parameter name)items[i].retailPriceInclVat
: Total product price excluding VAT (ignore the parameter name)
Selecting a Product
The order submit API can receive product information in two ways:
-
Using
productUid
:"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
-
Using
productName
andproductVariant
:"productName": "Framed Poster", "productVariant": { "FrameColour": "Black", "PaperSize": "A3" }
Do not use both methods in the same order request.
Selecting a Shipping Method
The shipmentMethodUid
field can accept:
- Specific shipment method UIDs (e.g.,
fed_ex_2_day
) - Shipping carrier names (e.g.,
DHL
) - Shipping option tiers (e.g.,
Express
)
Multiple shipping methods can be provided as a comma-separated string, and the system will use the cheapest option.
Response Format
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "test",
"createdAt": "2024-07-17T10:23:28+00:00"
}
Metadata usage throughout GelatoConnect
Metadata provided at both order and item levels in order requests can be used by a number of tools within GelatoConnect and also returned in postbacks. This is particularly valuable for those who need to maintain data continuity between their systems.
Order-Level Metadata:
Order-level metadata applies to the entire order and is defined at the top level of the request.
{
"orderReferenceId": "ORD-12345",
"orderType": "order",
"currency": "USD",
"metadata": [
{
"key": "campaign",
"value": "summer_promo"
},
{
"key": "source",
"value": "web"
}
],
"shippingAddress": {...},
"items": [...]
}
Item-Level Metadata:
Item-level metadata applies to specific items and is defined within each item in the items array.
{
"orderReferenceId": "ORD-12345",
"orderType": "order",
"currency": "USD",
"shippingAddress": {...},
"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,
"metadata": [
{
"key": "position",
"value": "A1"
},
{
"key": "machine",
"value": "Printer3"
}
],
"files": [...]
}
]
}
File-Level Metadata:
File-level metadata applies to specific files and is defined within each file in the files array. In the example below it is used to define alternative text for the image embroideryText associated with the file.
{
"orderReferenceId": "ORD-12345",
"orderType": "order",
"currency": "USD",
"shippingAddress": {...},
"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://www.example.com/path/to/printfile.pdf",
"metadata": [
{
"key": "embroideryText",
"value": "James"
}
]
}
]
}
]
}