Skip to content

Quote order

Use the Quote API to get the list of shipping options and Promise UIDs for your product.

POST https://api.gelato.com/v2/quote

Request example

$ curl -X POST \
   https://api.gelato.com/v2/quote \
   -H 'Content-Type: application/json' \
   -H 'X-API-KEY: {{apiKey}}' \
   -d '{
        "order": {
            "orderReferenceId": "{{MyOrderId}}",
            "customerReferenceId": "{{MyCustomerId}}",
            "currencyIsoCode": "USD"
        },
        "recipient": {
             "countryIsoCode": "US",
             "companyName": "Example",
             "firstName": "Paul",
             "lastName": "Smith",
             "addressLine1": "451 Clarkson Ave",
             "addressLine2": "Brooklyn",
             "stateCode": "NY",
             "city": "New York",
             "postcode": "11203",
             "email": "[email protected]",
             "phone": "123456789"
         },
        "products": [
            {
                "itemReferenceId": "{{MyItemId1}}",
                "productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
                "pdfUrl": "https://cdn-origin.gelato-api-dashboard.ie.live.gelato.tech/docs/sample-print-files/business_card_empty.pdf",
                "quantity": 100
            },
            {
                "itemReferenceId": "{{MyItemId2}}",
                "productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
                "pdfUrl": "https://cdn-origin.gelato-api-dashboard.ie.live.gelato.tech/docs/sample-print-files/logo.png",
                "quantity": 30,
                "options": [
                    {
                        "type": "envelope",
                        "productUid": "blank-envelopes_pf_a7-env_pt_120-g-env",
                        "quantity": 40  
                    }
                ]
            }
        ]
    }'

Response example

{
    "orderReferenceId": "{{MyOrderId}}",
    "production": {
        "itemReferenceId": [
            "{{MyItemId1}}",
            "{{MyItemId2}}"
        ],
        "productionCountry": "US",
        "productionTimeZone": "America/Chicago",
        "shipments": [
            {
                "promiseUid": "d_5d5f9f7b5faf183b4504cfbc",
                "name": "UPS Surepost",
                "uid": "ups_surepost",
                "price": 7.29,
                "minDeliveryDays": 6,
                "maxDeliveryDays": 7,
                "minDeliveryDate": "2019-08-29",
                "maxDeliveryDate": "2019-08-30",
                "serviceType": "normal",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            },
            {
                "promiseUid": "d_5d5f9f7b5faf183b456df752",
                "name": "UPS Ground Commercial",
                "uid": "ups_ground_commercial",
                "price": 6.61,
                "minDeliveryDays": 5,
                "maxDeliveryDays": 6,
                "minDeliveryDate": "2019-08-28",
                "maxDeliveryDate": "2019-08-29",
                "serviceType": "normal",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            },
            {
                "promiseUid": "d_5d5f9f7b5faf183b45c6b7b0",
                "name": "UPS Next Day Commercial",
                "uid": "ups_next_day_commercial",
                "price": 28.25,
                "minDeliveryDays": 4,
                "maxDeliveryDays": 4,
                "minDeliveryDate": "2019-08-27",
                "maxDeliveryDate": "2019-08-27",
                "serviceType": "express",
                "methodType": "both",
                "totalWeight": 613,
                "numberOfParcels": 1,
                "promiseExpirationDateTime": "2019-08-24T08:10:33+00:00"
            }
        ]
    }
}

Query Parameters

Parameter Type Description
order (required) OrderObject Order details.
recipient (required) RecipientObject Recipient address information.
products (required) ProductObject[] List of products.
allowMultipleProductionLocations (optional) boolean By default Quote API will return an error should Gelato not be able to produce all products from the quote request at a single production location. If the parameter "allowMultipleProductionLocations" is passed, then you will get deliveryPromiseUid in the response. Once you pass it to the order create API, our system will create multiple orders (one per production location) and you will see them all in the dashboard.

OrderObject

Parameter Type Description
customerReferenceId (required) string Reference to your internal customer id.
orderReferenceId (required) string Reference to your internal order id.
currencyIsoCode (required) string Currency iso code in ISO 4217 standard. Shipping prices will be converted to the currency specified here.
Supported currencies: EUR, USD, JPY, BGN, CZK, DKK, GBP, HUF, PLN, RON, SEK, CHF, ISK, NOK, HRK, RUB, TRY, AUD, BRL, CAD, CNY, HKD, IDR, ILS, INR, KRW, MXN, MYR, NZD, PHP, SGD, THB, ZAR, CLP, AED, COP, PEN

ProductObject

Parameter Type Description
itemReferenceId (required) string Reference to your internal order item id. Must be unique within order.
productUid (required) string Type of printing product in product uid format.
pageCount (optional) integer The page count for multipage products. This parameter is only needed for multi-page products. All pages in the product, including front and back cover are included in the count. For example for a Wire-o Notebook there are 112 inner pages (56 leaves), 2 front (outer and inside) and 2 back cover (outer and inside) pages, total 116 pages. The pageCount is 116. Read more
pdfUrl (required) string Url to the product pdf file. The preference is to provide the pdf file in one of the compatible PDF/X standards, for example in PDF/X-1a:2003 or PDF/X-4 standard. For products with one print areas, we support: JPEG, PNG and PDF. For products with more than one print area we support multi-page PDFs.
quantity (required) integer The product quantity. Define how many copies of product should be printed. The minimum value is 1
options (optional) ProductOption[] Array of additional product options

ProductOption

Product options is used to specify additional product attributes or for adding non-printed product additions (such as envelopes). The parameter type must be specified to define the product option category. Currently only envelope is supported as a valid type option.

Use the envelope option to add blank envelopes to product

{
    "type": "envelope",
    "productUid": "blank-envelopes_pf_c6_pt_145-g-env-white",
    "quantity": 40
}
Parameter Type Description
type (required) string A valid option category (currently only envelope.
productUid (required) string Specific option category product in product uid format.
quantity (required) integer The option quantity. For example how many envelopes should be added to your product. The minimum value is 1

RecipientObject

Please note that addresses for China (CN), Japan (JP), South Korea (KR) and Russia (RU) must be entered in local language due to shipping providers' requirements. Please see detailed requirements by field below

Parameter Type Description
countryIsoCode (required) string The two-character ISO 3166-1 code that identifies the country or region. Please note: the country code for United Kingdom is GB and not UK as used in the top-level domain names for that country.
Pattern: ^[A-Z]{2}$
firstName (required) string The first name of the recipient at this address.
Maximum length is 25 characters. It can be any symbol or character.
lastName (required) string The last name of the recipient at this address.
Maximum length is 25 characters. It can be any symbol or character.
companyName (optional) string The company name of the recipient at this address.
Maximum length is 60 characters. It can be any symbol or character.
addressLine1 (required) string The first line of the address. For example, number, street, and so on.
Maximum length is 35 characters. It must be in local language for Russia (RU), China (CN), Japan (JP) and South Korea (KR). Up to 10 Latin characters are allowed.
addressLine2 (optional) string The second line of the address. For example, suite or apartment number.
Maximum length is 35 characters. It must be in local language for Russia (RU), China (CN), Japan (JP) and South Korea (KR). Up to 10 Latin characters are allowed.
city (required) string The city name.
Maximum length is 30 characters. It must be in local language for Russia (RU), China (CN), Japan (JP) and South Korea (KR).
postcode (required) string The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
Maximum length is 15 characters
stateCode (optional) string The code for a US state or the equivalent for other countries. Required for requests if the address is in one of these countries: Australia, Canada or United States.
Maximum length is 35 characters. See list of state codes
email (required) string The email address for the recipient.
Pattern: .+@["-].+$
phone (optional) string The phone number, in E.123 format.
Maximum length is 25 characters
isBusiness (optional) bool Boolean value, declares the recipient being a business. Use if tax for recipient country is different for private and business customers (e.g. in Brazil) to change federalTaxId field type. Mandatory for Brazil if recipient is a company.
federalTaxId (optional) string The Federal Tax identification number of recipient. Use to provide CPF/CNPJ of a Brazilian recipient. Mandatory for Brazil. In order to supply CNPJ instead of CPF, set isBusiness field to true.
stateTaxId (optional) string The State Tax identification number of recipient. Use to provide IE of a Brazilian recipient. Mandatory for Brazil if recipient is a company. In order to supply this field, set isBusiness field to true.
registrationStateCode (optional) string The code number for a US state or the equivalent for other countries that defines state where recipient company is registered. Mandatory for Brazil if recipient is a company. In order to supply this field, set isBusiness field to true.

Response

Parameter Type Description
orderReferenceId (required) string Reference to your internal order id.
production (required) ProductionObject Production information with shipment options.

ProductionObject parameters

Parameter Type Description
itemReferenceId (required) string[] List of your internal item IDs.
productionCountry (required) string The two-character ISO 3166-1 code that identifies the production country that will produce the product.
productionTimeZone (required) string Production location time zone in ISO 8601 standard.
shipments (required) ShippingObject[] List of available shipping options.

ShippingObject parameters

Parameter Type Description
promiseUid (required) string The promise uid is unique for each shipping option. The promise expires after 24 hours, then a new quote request must be done to get a new promise. This value should be used for the Order create API.
name (required) string Shipment method name.
uid (required) string Shipment method uid.
price (required) float Shipping price in the currency as provided in order.currencyIsoCode parameter.
minDeliveryDays (required) integer Minimum days estimate to produce and deliver the product.
maxDeliveryDays (required) integer Maximum days estimate to produce and deliver the product.
minDeliveryDate (required) string Minimum date estimate to produce and deliver the product.
maxDeliveryDate (required) string Maximum date estimate to produce and deliver the product
serviceType (required) string Shipping service type. Can be: normal, express or pallet.
methodType (required) string Shipping methods type. Can be: private, business or both.
totalWeight (required) integer Total weight of the product in grams, including the weight of the parcel.
numberOfParcels (required) integer Count of shipping parcels. Depending on the product type and quantity ordered, the product might be split into parcels if a weight of the product exceeds the available weight or size for the shipping method.
promiseExpirationDateTime (required) string Date and time in ISO 8601 format when the Promise UID will be expired and can not be used anymore.

Select one of the Promise UIDs returned and then create the order, that's it. The order is now placed and will be printed and shipped.