Skip to content

Stock availability

Use this endpoint to get information about the availability of stock-able products in different regions.

POST https://product.gelatoapis.com/v3/stock/region-availability

Request example

$ curl --location --request POST 'https://product.gelatoapis.com/v3/stock/region-availability' \
-H 'X-API-KEY: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
  "products": [
    "wall_hanger_product_whs_290-mm_whc_white_whm_wood_whp_w14xt20-mm",
    "frame_and_poster_product_frs_300x400-mm_frc_black_frm_wood_frp_w12xt22-mm_gt_plexiglass__pf_300x400-mm_pt_170-gsm-coated-silk_cl_4-0_ct_none_prt_none_hor",
    "non-existing-product-uid"
  ]
}'

Response example

{
  "productsAvailability": [
    {
      "productUid": "wall_hanger_product_whs_290-mm_whc_white_whm_wood_whp_w14xt20-mm",
      "availability": [
        {
          "stockRegionUid": "US-CA",
          "status": "in-stock"
        },
        {
          "stockRegionUid": "EU",
          "status": "out-of-stock-replenishable"
        },
        {
          "stockRegionUid": "OC",
          "status": "in-stock"
        },
        {
          "stockRegionUid": "AS",
          "status": "out-of-stock"
        },
        {
          "stockRegionUid": "SA",
          "status": "out-of-stock"
        },
        {
          "stockRegionUid": "ROW",
          "status": "in-stock"
        }
      ]
    },
    {
      "productUid": "frame_and_poster_product_frs_300x400-mm_frc_black_frm_wood_frp_w12xt22-mm_gt_plexiglass__pf_300x400-mm_pt_170-gsm-coated-silk_cl_4-0_ct_none_prt_none_hor",
      "availability": [
        {
          "stockRegionUid": "US-CA",
          "status": "in-stock"
        },
        {
          "stockRegionUid": "EU",
          "status": "in-stock"
        },
        {
          "stockRegionUid": "OC",
          "status": "out-of-stock-replenishable"
        },
        {
          "stockRegionUid": "AS",
          "status": "in-stock"
        },
        {
          "stockRegionUid": "SA",
          "status": "out-of-stock"
        },
        {
          "stockRegionUid": "ROW",
          "status": "out-of-stock-replenishable"
        }
      ]
    },
    {
      "productUid": "non-existing-product-uid",
      "availability": [
        {
          "stockRegionUid": "US-CA",
          "status": "not-supported"
        },
        {
          "stockRegionUid": "EU",
          "status": "not-supported"
        },
        {
          "stockRegionUid": "OC",
          "status": "not-supported"
        },
        {
          "stockRegionUid": "AS",
          "status": "not-supported"
        },
        {
          "stockRegionUid": "SA",
          "status": "not-supported"
        },
        {
          "stockRegionUid": "ROW",
          "status": "not-supported"
        }
      ]
    }
  ]
}

Request parameters

Parameter Type Description
products (required) string[] Array of product UIDs to check availability for. Product UIDs can be taken from Product Search API. Minimum number of requested products: 1. Max number of requested products: 250.

Successful response

Response parameters

Parameter Type Description
productsAvailability (required) ProductAvailability[] Array of product's availability in region.

ProductAvailability parameters

Parameter Type Description
productUid (required) string Product UID from the request.
availability (required) Availability Availability in region.

Availability parameters

Parameter Type Description
stockRegionUid (required) string One of defined stock region UIDs.
status (required) string One of the possible availability statuses.

Parameter status can be one of 5 possible values:

  • in-stock - Product is in stock at one of Gelato Partners and can be be delivered to given region by at least one of the partners.

  • out-of-stock-replenishable - Product is temporarily out of stock at Gelato Partners but is in stock at the Gelato Hub which acts as a fallback solution, thus still can be delivered to the given region. Meantime the product is about to be replenished soon at the partners.

  • out-of-stock - Product is currently out of stock at both Gelato Partners and the Gelato Hub, thus cannot be delivered to the given region.

  • non-stockable - Product is not stock-able, thus an information if it is currently in stock or out of stock cannot be given. Example stock-able products are frames, wall hangers, envelopes and combined versions of them like framed poster. Example of non-stock-able products: printable mugs, posters, canvases, cards etc.

  • not-supported - Product is not recognized by Gelato.

Products are constantly being replenished at Gelato Partners and Gelato Hub, so availability can change frequently.

Error response

Error response example:

{
  "code": "invalid_request_too_many_products",
  "message": "Too many products requested: 273 of maximum 250."
}
HTTP Status Code Code Message
400 invalid_request_too_many_products Too many products requested: N of maximum 250.
400 invalid_request_products_not_provided No products provided, at least one is required.
401 invalid_api_key_provided Access denied. Token is invalid.
500 internal_server_error We had a problem with our server. Problem reported. Try again later.

Regions definition

Defined list of regions with countries that are included to them is the following.

Region: US and Canada

Stock region UID: US-CA

  • United States
  • Canada

Region: South America

Stock region UID: SA

  • Brazil
  • Argentina
  • Bolivia
  • Chile
  • Colombia
  • Ecuador
  • Guyana
  • Paraguay
  • Peru
  • Suriname
  • Uruguay
  • Venezuela

Region: Oceania

Stock region UID: OC

  • Australia
  • New Zealand

Region: Asia

Stock region UID: AS

  • Singapore
  • Vietnam
  • Brunei
  • Cambodia
  • China
  • Indonesia
  • Japan
  • Laos
  • Thailand
  • Taiwan
  • South Korea
  • Myanmar
  • Philippines
  • Malaysia

Region: Europe

Stock region UID: EU

  • Albania
  • Andorra
  • Austria
  • Belarus
  • Belgium
  • Bosnia and Herzegovina
  • Bulgaria
  • Croatia
  • Cyprus
  • Czechia
  • Denmark
  • Estonia
  • Finland
  • France
  • Georgia
  • Germany
  • Greece
  • Hungary
  • Iceland
  • Ireland
  • Italy
  • Kosovo
  • Latvia
  • Liechtenstein
  • Lithuania
  • Luxembourg
  • Malta
  • Moldova
  • Monaco
  • Montenegro
  • Netherlands
  • North Macedonia
  • Norway
  • Poland
  • Portugal
  • Romania
  • Russia
  • San Marino
  • Serbia
  • Slovakia
  • Slovenia
  • Spain
  • Sweden
  • Switzerland
  • Turkey
  • Ukraine
  • United Kingdom
  • Vatican City

Region: Rest of the world

Stock region UID: ROW

  • Afghanistan
  • Algeria
  • Angola
  • Anguilla
  • Antigua and Barbuda
  • Armenia
  • Aruba
  • Azerbaijan
  • Bahamas
  • Bahrain
  • Bangladesh
  • Barbados
  • Belize
  • Benin
  • Bermuda
  • Bhutan
  • Bonaire, Saint Eustatius and Saba
  • Botswana
  • Bouvet Island
  • Burkina Faso
  • Burundi
  • Cameroon
  • Cape Verde
  • Cayman Islands
  • Central African Republic
  • Chad
  • Christmas Island
  • Cocos (Keeling) Islands
  • Comoros
  • Congo
  • Congo, the Democratic Republic of the
  • Cook Islands
  • Costa Rica
  • Cuba
  • Ivory Coast
  • Djibouti
  • Dominica
  • Dominican Republic
  • Egypt
  • El Salvador
  • Equatorial Guinea
  • Eritrea
  • Ethiopia
  • Falkland Islands (Malvinas)
  • Faroe Islands
  • Federated States of Micronesia
  • Fiji
  • French Guiana
  • French Polynesia
  • Gabon
  • Gambia
  • Ghana
  • Gibraltar
  • Greenland
  • Grenada
  • Guadeloupe
  • Guatemala
  • Guernsey
  • Guinea
  • Guinea-Bissau
  • Haiti
  • Honduras
  • Hong Kong
  • India
  • Iran
  • Iraq
  • Israel
  • Jamaica
  • Jersey
  • Jordan
  • Kazakhstan
  • Kenya
  • Kiribati
  • Kuwait
  • Kyrgyzstan
  • Lebanon
  • Lesotho
  • Liberia
  • Libya
  • Macao
  • Madagascar
  • Malawi
  • Maldives
  • Mali
  • Marshall Islands
  • Martinique
  • Mauritania
  • Mauritius
  • Mayotte
  • Mexico
  • Mongolia
  • Montserrat
  • Morocco
  • Mozambique
  • Namibia
  • Nauru
  • Nepal
  • Netherlands Antilles
  • New Caledonia
  • Nicaragua
  • Niger
  • Nigeria
  • Niue
  • North Korea
  • Oman
  • Pakistan
  • Palau
  • Palestinian Territory, Occupied
  • Panama
  • Papua New Guinea
  • Pitcairn
  • Qatar
  • Rwanda
  • Réunion
  • Saint Helena, Ascension and Tristan da Cunha
  • Saint Kitts and Nevis
  • Saint Lucia
  • Saint Pierre and Miquelon
  • Samoa
  • Sao Tome and Principe
  • Saudi Arabia
  • Senegal
  • Seychelles
  • Sierra Leone
  • Solomon Islands
  • Somalia
  • South Africa
  • South Sudan
  • Sri Lanka
  • St. Vincent & the Grenadines
  • Sudan
  • Svalbard and Jan Mayen
  • Swaziland
  • Syria
  • Tajikistan
  • Tanzania, United Republic of
  • Timor-Leste
  • Togo
  • Tonga
  • Trinidad and Tobago
  • Tunisia
  • Turkmenistan
  • Turks and Caicos Islands
  • Tuvalu
  • Uganda
  • United Arab Emirates (UAE)
  • Uzbekistan
  • Vanuatu
  • Virgin Islands, British
  • Wallis and Futuna
  • Western Sahara
  • Yemen
  • Zambia
  • Zimbabwe

Countries currently not supported by Gelato

  • Åland Islands
  • British Indian Ocean Territory
  • French Southern Territories
  • Heard Island and McDonald Islands
  • Isle of Man
  • Norfolk Island
  • South Georgia and the South Sandwich Islands
  • Tokelau
  • United States Minor Outlying Islands