Skip to content

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 same files 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)
email 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 in
  • retailShippingPriceInclVat: 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:

  1. Using productUid:

    "productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
    

  2. Using productName and productVariant:

    "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"
             }
           ]
        }
      ]
    }
  ]
}