Quote order
Use the Quote API to get the list of shipping methods and the product requested.
POST https://order.gelatoapis.com/v3/orders:quote
Request example
$ curl -X POST \
https://order.gelatoapis.com/v3/orders:quote \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {{apiKey}}' \
-d '{
"orderReferenceId": "{{myOrderId}}",
"customerReferenceId": "{{myCustomerId}}",
"currency": "USD",
"allowMultipleQuotes": false,
"recipient": {
"country": "US",
"companyName": "Example",
"firstName": "Paul",
"lastName": "Smith",
"addressLine1": "451 Clarkson Ave",
"addressLine2": "Brooklyn",
"state": "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",
"fileUrl": "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",
"fileUrl": "https://cdn-origin.gelato-api-dashboard.ie.live.gelato.tech/docs/sample-print-files/logo.png",
"quantity": 30
}
]
}'
Response example
{
"orderReferenceId": "{{myOrderId}}",
"quotes":[
{
"id": "c22cf4c2-0249-48d0-ac51-c47d24c01f02",
"itemReferenceIds": [
"{{myItemId1}}",
"{{myItemId2}}"
],
"fulfillmentCountry": "US",
"shipmentMethods": [
{
"name": "UPS Surepost",
"shipmentMethodUid": "ups_surepost",
"price": 5.11,
"currency": "EUR",
"minDeliveryDays": 6,
"maxDeliveryDays": 7,
"minDeliveryDate": "2019-08-29",
"maxDeliveryDate": "2019-08-30",
"type": "normal",
"isPrivate": true,
"isBusiness": true,
"totalWeight": 613,
"numberOfParcels": 1,
"incoTerms": "DDP"
},
{
"name": "UPS Ground Commercial",
"shipmentMethodUid": "ups_ground_commercial",
"price": 5.11,
"currency": "EUR",
"minDeliveryDays": 5,
"maxDeliveryDays": 6,
"minDeliveryDate": "2019-08-28",
"maxDeliveryDate": "2019-08-29",
"type": "normal",
"isPrivate": true,
"isBusiness": true,
"totalWeight": 613,
"numberOfParcels": 1
},
{
"name": "UPS Next Day Commercial",
"shipmentMethodUid": "ups_next_day_commercial",
"price": 25.11,
"currency": "EUR",
"minDeliveryDays": 4,
"maxDeliveryDays": 4,
"minDeliveryDate": "2019-08-27",
"maxDeliveryDate": "2019-08-27",
"type": "express",
"isPrivate": true,
"isBusiness": true,
"totalWeight": 613,
"numberOfParcels": 1
}
],
"products": [
{
"itemReferenceId": "{{myItemId1}}",
"productUid": "cards_pf_bx_pt_110-lb-cover-uncoated_cl_4-4_hor",
"quantity": 100,
"price": 25.11,
"currency": "EUR"
},
{
"itemReferenceId": "{{myItemId2}}",
"productUid": "cards_pf_5r_pt_100-lb-cover-coated-silk_cl_4-4_hor",
"quantity": 100,
"price": 25.11,
"currency": "EUR"
}
]
}
]
}
Request
| Parameter | Type | Description |
|---|---|---|
| orderReferenceId (required) | string | Reference to your internal order id. |
| customerReferenceId (required) | string | Reference to your internal customer id. |
| recipient (required) | RecipientObject | Recipient address information. |
| products (required) | ProductObject[] | List of products. |
| currency (required) | string | Currency iso code in ISO 4217 standard. Currency that the order should be charged in. 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 Note: It is applicable only for customers using wallets or credit cards for payments. |
| allowMultipleQuotes (optional) | boolean | This parameter controls if the quote returned shall allow for separate quotes per fulfillment facility; true will permit this and false will limit to a single quote with aggregated min/max delivery days. Default: true. Note: We always try to fulfill your order from a single fulfillment facility, if this is not possible multiple quotes will be returned. |
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 |
| fileUrl (required) | string | Url to the product 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. |
| quantity (required) | integer | The product quantity. Define how many copies of product should be printed. 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 |
|---|---|---|
| country (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 |
| state (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. |
| quotes (required) | QuoteObject | List of quotes with production information and shipment methods. |
QuoteObject parameters
| Parameter | Type | Description |
|---|---|---|
| id (required) | string | Quote Id. |
| itemReferenceIds (required) | string[] | List of your internal item IDs. |
| fulfillmentCountry (required) | string | The two-character ISO 3166-1 code that identifies the country where the product will be shipped from. |
| shipmentMethods (required) | ShipmentMethodObject[] | List of available shipping methods. |
| products (required) | ProductObject[] | List of products. |
ShipmentMethodObject parameters
| Parameter | Type | Description |
|---|---|---|
| name (required) | string | The shipment method name. |
| shipmentMethodUid (required) | string | The shipment method uid. |
| price (required) | double | The shipping price. |
| currency (required) | string | The currency of the sipping price. |
| 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 |
| type (required) | string | The shipping service type. Can be: normal, standard, express or pallet. |
| isPrivate (required) | boolean | The shipping method type is private. |
| isBusiness (required) | boolean | The shipping method type is business. |
| 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. |
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 |
| quantity (required) | integer | The product quantity. |
| price (required) | float | The product price |
| currency (required) | string | The currency of price |