Skip to main content
All CollectionsConnect WorkflowOrder intakeAPI Integration
Order Management API Documentation

Order Management API Documentation

Updated this week

Introduction

Welcome to the Order Management API documentation. This API allows you to submit orders, cancel orders, retrieve order details, search orders, and update shipping addresses or methods within the GelatoConnect system. The API is organized around REST principles and uses standard HTTPS methods to interact with resources. All responses are returned in JSON format, including errors.

Authentication

All Order Management API calls require authentication using a valid API key and secret provided in the header of each call. All communication must be done through HTTPS; calls made over plain HTTP will fail.

Authentication Method

  1. Add the X-API-KEY header to your request

  2. Set the value using the format: key:secret

Example:

X-API-KEY: your-key:your-secret

Your specific API key and secret will be provided when setting up a connector for your customer.

Rate Limits

The API imposes restrictions on the number of requests a user or client can make within a specified period. All requests count toward your personal rate limit of 100 requests per second.

Why Rate Limits Exist

Rate limits serve several important purposes:

  • Protecting against abuse or misuse of the API

  • Ensuring fair access for all users

  • Preventing service disruptions due to excessive traffic

Retry Logic for Rate Limit Errors

If you exceed the API rate limit, you'll receive a 429 status code. To minimize the impact on your workloads, implement these retry techniques:

  1. Retry: Automatically reattempt failed requests. Implement retry logic in your application code for all API calls.

  2. Exponential Backoff: Use progressively longer waits between retries for consecutive error responses. Implement a maximum delay interval and a maximum number of retries based on the operation being performed.

  3. Jitter: Add a random amount of time before retrying requests to prevent all clients from retrying simultaneously. This helps distribute the load and prevents successive collisions.

For more information on retry strategies, see:

Response Codes

The Order Management API uses conventional HTTP response codes to indicate the success or failure of requests:

  • 2xx Codes: Indicate success

  • 4xx Codes: Indicate structural or data errors in the request (e.g., missing required parameters, order not found)

  • 5xx Codes: Indicate server errors (these are rare)

API Endpoints

Submit Order

Submit an order in a single request.

Endpoint: 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 (click here)

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",
  "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

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

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

Type of file

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.

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"

  1. 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": [...]
    }
  ]
}

Cancel Order

Stop and cancel the production and shipment process for an order. This is only possible until the order status changes to "shipped".

Endpoint: POST /{orderCancelUrl}

This endpoint can accept either the Order ID (provided in the submit order response) or the Order Reference ID (your internal order ID).

Using Order ID

POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel

Using Order Reference ID

POST /{orderCancelUrl}/test/cancel

Response Format

{
  "code": 200,
  "message": "OK"
}

Update Shipment

Modify the shipping method or update the shipping address until the order has moved to status "shipped".

Endpoint: PUT /{updateShipmentURL}

This endpoint can accept either the Order ID or the Order Reference ID.

Request Format

{
  "shipmentMethodUid": "fed_ex_2_day",
  "shippingAddress": {
    "country": "GB",
    "firstName": "Alexis",
    "lastName": "Apollo",
    "addressLine1": "Longusta str. 4",
    "addressLine2": "app. 144",
    "city": "myCity",
    "postCode": "111111",
    "state": "myState",
    "email": "[email protected]",
    "phone": "+34 111444111",
    "companyName": "Company_example",
    "isBusiness": false,
    "federalTaxId": "",
    "stateTaxId": "",
    "registrationState": ""
  }
}

You can update either the shipping method, the shipping address, or both. At least one of these fields must be included in the request.

Request Parameters

Parameter

Type

Required

Description

shipmentMethodUid

string

Optional*

New shipping method (*At least one of shipmentMethodUid or shippingAddress must be provided)

shippingAddress

object

Optional*

New shipping address details (*At least one of shipmentMethodUid or shippingAddress must be provided)

Response Format

{
  "shippingAddress": {
    "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1",
    "orderId": "148c5a06-35c9-40d3-8ef7-e85eb2da317d",
    "country": "GB",
    "firstName": "Test Order",
    "lastName": "4",
    "companyName": "company_example",
    "addressLine1": "address example 1",
    "addressLine2": "address example 2",
    "city": "myCity",
    "postCode": "111111",
    "state": "",
    "email": "[email protected]",
    "phone": "+34 111444222",
    "isBusiness": false,
    "federalTaxId": "",
    "stateTaxId": "",
    "registrationState": ""
  },
  "shipment": {
    "shipmentMethodUid": "fed_ex_2_day",
    "shipmentMethodName": "DHL Global Parcel",
    "fulfillmentCountry": "DE",
    "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa",
    "packageCount": 1,
    "initialMinDeliveryDate": "2024-11-16",
    "initialMaxDeliveryDate": "2024-11-16",
    "serviceType": "normal"
  }
}

Get Order

Retrieve information about an existing order.

Endpoint: GET /{getOrderURL}/{order_id}

You can use either the Gelato Order ID or your Order Reference ID.

Response Format

The response will include detailed information about the order, including:

  • Order details (ID, reference, status, etc.)

  • Shipping address

  • Items ordered with product details

  • Shipment information (method, tracking, etc.)

  • Financial information

Response example (click here)

{
  "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
  "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
  "orderReferenceId": "healthcheck_middleware_order_create_2024-12-02-11:05:06_1991",
  "customerReferenceId": "sandbox-customer",
  "fulfillmentStatus": "failed",
  "financialStatus": "canceled",
  "currency": "USD",
  "shippingAddress": {
    "id": "29de7336-95a9-48d2-aa85-d7d40e6ea65c",
    "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
    "country": "GB",
    "firstName": "TEST",
    "lastName": "PRINT",
    "companyName": "",
    "addressLine1": "19 June Lewis Way",
    "addressLine2": "",
    "city": "Fairford",
    "postCode": "GL7 4GH",
    "state": "",
    "email": "[email protected]",
    "phone": "1111111119",
    "isBusiness": false,
    "federalTaxId": null,
    "stateTaxId": null,
    "registrationState": null
  },
  "items": [
    {
      "id": "e9f6de69-670b-47c5-a953-3710cac053a1",
      "itemReferenceId": "1111111111",
      "productUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver",
      "storeProductVariantId": null,
      "storeProductId": null,
      "files": [
        {
          "id": null,
          "type": "default",
          "url": "https://URLexample.com/order",
          "threadColors": [],
          "isVisible": false,
          "fitMethod": null,
          "fillMethod": null,
          "mimeType": "application/pdf",
          "metadata": []
        }
      ],
      "processedFileUrl": null,
      "quantity": 1,
      "options": [],
      "category": "Posters",
      "productCategoryUid": "wall-art",
      "productTypeUid": "poster",
      "productNameUid": "classic-semi-glossy-poster",
      "productName": "Classic Semi-Glossy Poster",
      "fulfillmentStatus": "failed",
      "pageCount": null,
      "printJobs": [],
      "eventLog": [],
      "previews": [
        {
          "type": "preview_default",
          "url": "https://URLexample.com/order"
        },
        {
          "type": "preview_thumbnail",
          "url": "https://URLexample.com/order"
        },
        {
          "type": "preview_flat",
          "url": "https://URLexample.com/order"
        }
      ],
      "designId": null,
      "productFileMimeType": "application/pdf",
      "finalProductUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver",
      "metadata": [
        {
          "key": "unitWeight",
          "value": "800"
        },
        {
          "key": "unitPrice",
          "value": ""
        },
        {
          "key": "supplierPartAuxiliaryId",
          "value": ""
        }
      ],
      "retailPriceInclVat": null,
      "attributes": [
        {
          "name": "size",
          "title": "Size",
          "value": "500x700-mm",
          "formattedValue": "50 x 70 cm"
        },
        {
          "name": "orientation",
          "title": "Orientation",
          "value": "ver",
          "formattedValue": "Vertical (portrait) orientation"
        }
      ],
      "itemReferenceName": null,
      "isIgnored": false,
      "price": 0,
      "customTrim": null,
      "fileUrl": "https://URLexample.com/order",
      "dpi": 0,
      "appServices": [],
      "filesSize": 3.8,
      "productVariant": []
    }
  ],
  "shipment": {
    "id": "33163694-1437-407f-99ef-57a0d579114f",
    "orderProductId": null,
    "shippingAddressId": "29de7336-95a9-48d2-aa85-d7d40e6ea65c",
    "promiseUid": "d_dfae1a1c58d230dbe73690a2",
    "packageCount": 1,
    "shipmentMethodUid": "dhl_global_parcel",
    "shipmentMethodName": "DHL Global Parcel",
    "isCheapest": true,
    "minDeliveryDays": 1,
    "maxDeliveryDays": 1,
    "minDeliveryDate": "2024-12-03",
    "maxDeliveryDate": "2024-12-03",
    "totalWeight": 139,
    "price": 0,
    "status": null,
    "packages": [],
    "fulfillmentCountry": "DE",
    "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa",
    "retailShippingPriceInclVat": null,
    "initialMinDeliveryDate": "2024-12-03",
    "initialMaxDeliveryDate": "2024-12-03",
    "serviceType": "normal",
    "speedType": ""
  },
  "receipts": [
    {
      "id": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc",
      "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
      "type": "contract",
      "currency": "USD",
      "items": [
        {
          "id": "a99224b0-6e96-430e-84dd-82995f274840",
          "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc",
          "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
          "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
          "type": "product",
          "referenceId": "e9f6de69-670b-47c5-a953-3710cac053a1",
          "title": "1x large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver",
          "currency": "USD",
          "priceBase": 0,
          "amount": 1,
          "priceInitial": 0,
          "discount": 0,
          "price": 0,
          "vat": 0,
          "priceInclVat": 0,
          "pricePlanId": null,
          "createdAt": "2024-12-02T11:05:09+00:00",
          "updatedAt": "2024-12-02T11:05:09+00:00"
        },
        {
          "id": "1d2936c3-eb3f-456d-94b9-b2be8c4eec50",
          "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc",
          "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
          "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
          "type": "shipment",
          "referenceId": "33163694-1437-407f-99ef-57a0d579114f",
          "title": "Delivery using DHL Global Parcel",
          "currency": "USD",
          "priceBase": 0,
          "amount": 1,
          "priceInitial": 0,
          "discount": 0,
          "price": 0,
          "vat": 0,
          "priceInclVat": 0,
          "pricePlanId": null,
          "createdAt": "2024-12-02T11:05:09+00:00",
          "updatedAt": "2024-12-02T11:05:09+00:00"
        },
        {
          "id": "b7d6899c-3a00-46eb-8d14-e9b3e2bb3e4e",
          "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc",
          "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
          "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
          "type": "packaging",
          "referenceId": "33163694-1437-407f-99ef-57a0d579114f",
          "title": "Packaging",
          "currency": "USD",
          "priceBase": 0,
          "amount": 1,
          "priceInitial": 0,
          "discount": 0,
          "price": 0,
          "vat": 0,
          "priceInclVat": 0,
          "pricePlanId": null,
          "createdAt": "2024-12-02T11:05:09+00:00",
          "updatedAt": "2024-12-02T11:05:09+00:00"
        }
      ],
      "createdAt": "2024-12-02T11:05:09+00:00",
      "updatedAt": "2024-12-02T11:05:10+00:00",
      "receiptNumber": "005-0014597660",
      "billingEntity": {
        "id": 218720,
        "companyName": "Gelato",
        "companyNumber": "",
        "companyVatNumber": "",
        "companyVatNumbers": [],
        "countryIsoCode": "DE",
        "country": "DE",
        "recipientName": "Alex Shiltcev",
        "addressLine1": "Something 1",
        "addressLine2": "",
        "city": "Berlin",
        "postCode": "10113",
        "stateCode": "",
        "state": "",
        "email": "[email protected]",
        "phone": "",
        "currencyIsoCode": "EUR",
        "currency": "EUR",
        "status": 1,
        "iossNumber": null,
        "invoiceType": null
      },
      "billingTag": "gelato-norway-de",
      "transactionType": "purchase",
      "productsPriceInitial": 0,
      "productsPriceDiscount": 0,
      "productsPrice": 0,
      "productsPriceVat": 0,
      "productsPriceInclVat": 0,
      "digitizationPriceInitial": 0,
      "digitizationPriceDiscount": 0,
      "digitizationPrice": 0,
      "digitizationPriceVat": 0,
      "digitizationPriceInclVat": 0,
      "shippingPriceInitial": 0,
      "shippingPriceDiscount": 0,
      "shippingPrice": 0,
      "shippingPriceVat": 0,
      "shippingPriceInclVat": 0,
      "packagingPriceInitial": 0,
      "packagingPriceDiscount": 0,
      "packagingPrice": 0,
      "packagingPriceVat": 0,
      "packagingPriceInclVat": 0,
      "discount": 0,
      "discountVat": 0,
      "discountInclVat": 0,
      "totalInitial": 0,
      "total": 0,
      "totalVat": 0,
      "totalInclVat": 0,
      "isCalculated": true
    }
  ],
  "createdAt": "2024-12-02T11:05:09+00:00",
  "refusalReason": "Order is failing as it’s going to be cross border and product retail prices are missing.",
  "channel": "api",
  "storeId": null,
  "orderedByUserId": null,
  "orderType": "order",
  "metadata": [
    {
      "key": "tenant-customer-id",
      "value": "02be1010-5f59-4504-a669-5cf88e84f627"
    },
    {
      "key": "tenant-customer-uid",
      "value": "sandbox-customer"
    }
  ],
  "billingEntity": {
    "id": 218720,
    "companyName": "Gelato",
    "companyNumber": "",
    "companyVatNumber": "",
    "companyVatNumbers": [],
    "countryIsoCode": "DE",
    "country": "DE",
    "recipientName": "Alex Shiltcev",
    "addressLine1": "Something 1",
    "addressLine2": "",
    "city": "Berlin",
    "postCode": "10113",
    "stateCode": "",
    "state": "",
    "email": "[email protected]",
    "phone": "",
    "currencyIsoCode": "EUR",
    "currency": "EUR",
    "status": 1,
    "iossNumber": null,
    "invoiceType": null
  },
  "retailCurrency": null,
  "paymentMethodType": null,
  "paymentMethodId": null,
  "prepaymentTransactionId": null,
  "orderedAt": "2024-12-02T11:05:07+00:00",
  "updatedAt": "2024-12-02T11:05:10+00:00",
  "connectedOrderIds": [],
  "discounts": [],
  "returnAddress": {
    "id": "6eeb262a-92ce-45a4-9cd6-128473a0acb0",
    "country": null,
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "postCode": null,
    "state": null,
    "email": null,
    "phone": null,
    "companyName": "Gelato Connect Sandbox"
  },
  "iossNumber": null,
  "refusalReasonCode": "missing_retail_prices",
  "refusalReasonDetails": null,
  "comment": "Order is failing as it’s going to be cross border and product retail prices are missing.",
  "digitizationId": null,
  "appServices": [],
  "shipmentMethodUid": "normal"
}

Search Orders

Retrieve a list of orders based on specific criteria.

Endpoint: POST /{searchOrdersURL}

Request Format

{
  "fulfillmentStatus": [
    "canceled",
    "delivered"
  ]
}

Request Parameters

Parameter

Type

Required

Description

fulfillmentStatus

string[]

Optional

Filter by order fulfillment status

financialStatus

string[]

Optional

Filter by order financial status

orderReferenceId

string

Optional

Filter by your internal order ID

orderReferenceIds

string[]

Optional

Filter by multiple internal order IDs

startDate

string

Optional

Filter by orders created after this date (ISO 8601 format)

endDate

string

Optional

Filter by orders created before this date (ISO 8601 format)

countries

string[]

Optional

Filter by shipping country codes

limit

number

Optional

Maximum number of results to return (default: 50, max: 100)

offset

number

Optional

Number of results to skip for pagination (default: 0)

Response Format

{
  "orders": [
    {
      "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
      "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
      "orderReferenceId": "orderref_123",
      "fulfillmentStatus": "failed",
      "financialStatus": "canceled",
      "currency": "USD",
      "totalInclVat": "0.00",
      "orderType": "order",
      "channel": "api",
      "storeId": null,
      "connectedOrderIds": [],
      "firstName": "TEST",
      "lastName": "PRINT",
      "country": "GB",
      "itemsCount": 1,
      "createdAt": "2024-12-02T11:05:09+00:00",
      "updatedAt": "2024-12-02T11:05:10+00:00",
      "orderedAt": "2024-12-02T11:05:07+00:00",
      "refusalReasonCode": "missing_retail_prices",
      "appServices": [],
      "customerReferenceId": "custref_456"
    }
  ]
}

Error Handling

When an API request fails, the response will include an error code and a descriptive message to help you identify and resolve the issue. Common error scenarios include:

  • 400 Bad Request: Invalid or missing parameters

  • 401 Unauthorized: Invalid or missing authentication credentials

  • 404 Not Found: The requested resource doesn't exist

  • 429 Too Many Requests: Rate limit exceeded

  • 500 Server Error: An unexpected error occurred on the server

Example error response:

{
  "code": 400,
  "message": "Invalid shipping address: Email is not a valid format"
}

For robust integration, implement proper error handling and retry logic as described in the Rate Limits section.

Getting Support

If you encounter issues or have questions about the API, please contact our support team at [email protected].

Include the following information in your support request:

  • The specific API endpoint you're using

  • Your request payload (with sensitive information redacted)

  • The error response you received

  • Any relevant timestamps

This will help our team address your issue more quickly and effectively.

Related Articles
Getting Started with GelatoConnect API
Introduction to Template Mappers in GelatoConnect
Template Mapper Examples
Working with Order API Endpoints
Postback Event Payload Reference Guide
Did this answer your question?