Country
The code designating a country/region, which generally follows ISO 3166-1 alpha-2 guidelines.
If a territory doesn't have a country code value in the enum, then it might be considered a subdivision
of another country. For example, the territories associated with Spain are represented by the country code ,
and the territories associated with the United States of America are represented by the country code .
Anchor to Valid valuesValid values
Ascension Island.
Andorra.
United Arab Emirates.
Afghanistan.
Antigua & Barbuda.
Anguilla.
Albania.
Armenia.
Netherlands Antilles.
Angola.
Argentina.
Austria.
Australia.
Aruba.
Ã…land Islands.
Azerbaijan.
Bosnia & Herzegovina.
Barbados.
Bangladesh.
Belgium.
Burkina Faso.
Bulgaria.
Bahrain.
Burundi.
Benin.
St. Barthélemy.
Bermuda.
Brunei.
Bolivia.
Caribbean Netherlands.
Brazil.
Bahamas.
Bhutan.
Bouvet Island.
Botswana.
Belarus.
Belize.
Canada.
Cocos (Keeling) Islands.
Congo - Kinshasa.
Central African Republic.
Congo - Brazzaville.
Switzerland.
Côte d’Ivoire.
Cook Islands.
Chile.
Cameroon.
China.
Colombia.
Costa Rica.
Cuba.
Cape Verde.
Curaçao.
Christmas Island.
Cyprus.
Czechia.
Germany.
Djibouti.
Denmark.
Dominica.
Dominican Republic.
Algeria.
Ecuador.
Estonia.
Egypt.
Western Sahara.
Eritrea.
Spain.
Ethiopia.
Finland.
Fiji.
Falkland Islands.
Faroe Islands.
France.
Gabon.
United Kingdom.
Grenada.
Georgia.
French Guiana.
Guernsey.
Ghana.
Gibraltar.
Greenland.
Gambia.
Guinea.
Guadeloupe.
Equatorial Guinea.
Greece.
South Georgia & South Sandwich Islands.
Guatemala.
Guinea-Bissau.
Guyana.
Hong Kong SAR.
Heard & McDonald Islands.
Honduras.
Croatia.
Haiti.
Hungary.
Indonesia.
Ireland.
Israel.
Isle of Man.
India.
British Indian Ocean Territory.
Iraq.
Iran.
Iceland.
Italy.
Jersey.
Jamaica.
Jordan.
Japan.
Kenya.
Kyrgyzstan.
Cambodia.
Kiribati.
Comoros.
St. Kitts & Nevis.
North Korea.
South Korea.
Kuwait.
Cayman Islands.
Kazakhstan.
Laos.
Lebanon.
St. Lucia.
Liechtenstein.
Sri Lanka.
Liberia.
Lesotho.
Lithuania.
Luxembourg.
Latvia.
Libya.
Morocco.
Monaco.
Moldova.
Montenegro.
St. Martin.
Madagascar.
North Macedonia.
Mali.
Myanmar (Burma).
Mongolia.
Macao SAR.
Martinique.
Mauritania.
Montserrat.
Malta.
Mauritius.
Maldives.
Malawi.
Mexico.
Malaysia.
Mozambique.
Namibia.
New Caledonia.
Niger.
Norfolk Island.
Nigeria.
Nicaragua.
Netherlands.
Norway.
Nepal.
Nauru.
Niue.
New Zealand.
Oman.
Panama.
Peru.
French Polynesia.
Papua New Guinea.
Philippines.
Pakistan.
Poland.
St. Pierre & Miquelon.
Pitcairn Islands.
Palestinian Territories.
Portugal.
Paraguay.
Qatar.
Réunion.
Romania.
Serbia.
Russia.
Rwanda.
Saudi Arabia.
Solomon Islands.
Seychelles.
Sudan.
Sweden.
Singapore.
St. Helena.
Slovenia.
Svalbard & Jan Mayen.
Slovakia.
Sierra Leone.
San Marino.
Senegal.
Somalia.
Suriname.
South Sudan.
São Tomé & PrÃncipe.
El Salvador.
Sint Maarten.
Syria.
Eswatini.
Tristan da Cunha.
Turks & Caicos Islands.
Chad.
French Southern Territories.
Togo.
Thailand.
Tajikistan.
Tokelau.
Timor-Leste.
Turkmenistan.
Tunisia.
Tonga.
Türkiye.
Trinidad & Tobago.
Tuvalu.
Taiwan.
Tanzania.
Ukraine.
Uganda.
U.S. Outlying Islands.
United States.
Uruguay.
Uzbekistan.
Vatican City.
St. Vincent & Grenadines.
Venezuela.
British Virgin Islands.
Vietnam.
Vanuatu.
Wallis & Futuna.
Samoa.
Kosovo.
Yemen.
Mayotte.
South Africa.
Zambia.
Zimbabwe.
Unknown Region.
Anchor to FieldsFields
- •INPUT OBJECT
The input fields for updating a backup region with exactly one required option.
- •OBJECT
Represents the address of a merchant's Business Entity.
- •INPUT OBJECT
The input fields for a buyer signal.
- •OBJECT
Represents a billing or shipping address for a company location.
- •INPUT OBJECT
The input fields to create or update the address of a company location.
- •INPUT OBJECT
The input fields for the context data that determines the pricing of a variant. Refer to Productfor more information on how to use this input object.
- •INPUT OBJECT
The context data that determines the publication status of a product.
- •OBJECT
The list of all the countries from the combined shipping zones for the shop.
- •OBJECT
The country-specific harmonized system code and ISO country code for an inventory item.
- •INPUT OBJECT
The input fields required to specify a harmonized system code.
- •OBJECT
The billing address of a credit card payment instrument.
- Anchor to CustomerPaymentInstrumentBillingAddress.countryCodeCustomer•OBJECT
Payment Instrument Billing Address. country Code The billing address of a payment instrument.
- Anchor to DeliveryCarrierService.availableServicesForCountriesDelivery•ARGUMENT
Carrier Service. available Services For Countries A carrier service (also known as a carrier calculated service or shipping service) provides real-time shipping rates to Shopify. Some common carrier services include Canada Post, FedEx, UPS, and USPS. The term carrier is often used interchangeably with the terms shipping company and rate provider.
Using the CarrierService resource, you can add a carrier service to a shop and then provide a list of applicable shipping rates at checkout. You can even use the cart data to adjust shipping rates and offer shipping discounts based on what is in the customer's cart.
Requirements for accessing the CarrierService resource
To access the CarrierService resource, add the
permission to your app's requested scopes. For more information, see API access scopes.Your app's request to create a carrier service will fail unless the store installing your carrier service meets one of the following requirements:
- It's on the Advanced Shopify plan or higher.
- It's on the Shopify plan with yearly billing, or the carrier service feature has been added to the store for a monthly fee. For more information, contact Shopify Support.
- It's a development store.
NoteIf a store changes its Shopify plan, then the store's association with a carrier service is deactivated if the store no long meets one of the requirements above.
Providing shipping rates to Shopify
When adding a carrier service to a store, you need to provide a POST endpoint rooted in the
property where Shopify can retrieve applicable shipping rates. The callback URL should be a public endpoint that expects these requests from Shopify.Example shipping rate request sent to a carrier service
{"rate": {"origin": {"country": "CA","postal_code": "K2P1L4","province": "ON","city": "Ottawa","name": null,"address1": "150 Elgin St.","address2": "","address3": null,"phone": null,"fax": null,"email": null,"address_type": null,"company_name": "Jamie D's Emporium"},"destination": {"country": "CA","postal_code": "K1M1M4","province": "ON","city": "Ottawa","name": "Bob Norman","address1": "24 Sussex Dr.","address2": "","address3": null,"phone": null,"fax": null,"email": null,"address_type": null,"company_name": null},"items": [{"name": "Short Sleeve T-Shirt","sku": "","quantity": 1,"grams": 1000,"price": 1999,"vendor": "Jamie D's Emporium","requires_shipping": true,"taxable": true,"fulfillment_service": "manual","properties": null,"product_id": 48447225880,"variant_id": 258644705304}],"currency": "USD","locale": "en"}}Example response
{"rates": [{"service_name": "canadapost-overnight","service_code": "ON","total_price": "1295","description": "This is the fastest option by far","currency": "CAD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"},{"service_name": "fedex-2dayground","service_code": "2D","total_price": "2934","currency": "USD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"},{"service_name": "fedex-priorityovernight","service_code": "1D","total_price": "3587","currency": "USD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"}]}The
address3,fax,, andfields are returned by specific ActiveShipping providers. For API-created carrier services, you should use only the following shipping address fields:address1address2cityzipprovincecountry
Other values remain as
nulland are not sent to the callback URL.Response fields
When Shopify requests shipping rates using your callback URL, the response object
ratesmust be a JSON array of objects with the following fields. Required fields must be included in the response for the carrier service integration to work properly.Field Required Description Yes The name of the rate, which customers see at checkout. For example: Expedited Mail.descriptionYes A description of the rate, which customers see at checkout. For example: Includes tracking and insurance.Yes A unique code associated with the rate. For example: .currencyYes The currency of the shipping rate. Yes The total price expressed in subunits. If the currency doesn't use subunits, then the value must be multiplied by 100. For example: for 5.00 CAD,for 1000 JPY.No Whether the customer must provide a phone number at checkout. No The earliest delivery date for the displayed rate. No The latest delivery date for the displayed rate to still be valid. Special conditions
- To indicate that this carrier service cannot handle this shipping request, return an empty array and any successful (20x) HTTP code.
- To force backup rates instead, return a 40x or 50x HTTP code with any content. A good choice is the regular 404 Not Found code.
- Redirects (30x codes) will only be followed for the same domain as the original callback URL. Attempting to redirect to a different domain will trigger backup rates.
- There is no retry mechanism. The response must be successful on the first try, within the time budget listed below. Timeouts or errors will trigger backup rates.
Response Timeouts
The read timeout for rate requests are dynamic, based on the number of requests per minute (RPM). These limits are applied to each shop-app pair. The timeout values are as follows.
RPM Range Timeout Under 1500 10s 1500 to 3000 5s Over 3000 3s NoteThese values are upper limits and should not be interpretted as a goal to develop towards. Shopify is constantly evaluating the performance of the platform and working towards improving resilience as well as app capabilities. As such, these numbers may be adjusted outside of our normal versioning timelines.
Server-side caching of requests
Shopify provides server-side caching to reduce the number of requests it makes. Any shipping rate request that identically matches the following fields will be retrieved from Shopify's cache of the initial response:
- variant IDs
- default shipping box weight and dimensions
- variant quantities
- carrier service ID
- origin address
- destination address
- item weights and signatures
If any of these fields differ, or if the cache has expired since the original request, then new shipping rates are requested. The cache expires 15 minutes after rates are successfully returned. If an error occurs, then the cache expires after 30 seconds.
- •ARGUMENT
A carrier service (also known as a carrier calculated service or shipping service) provides real-time shipping rates to Shopify. Some common carrier services include Canada Post, FedEx, UPS, and USPS. The term carrier is often used interchangeably with the terms shipping company and rate provider.
Using the CarrierService resource, you can add a carrier service to a shop and then provide a list of applicable shipping rates at checkout. You can even use the cart data to adjust shipping rates and offer shipping discounts based on what is in the customer's cart.
Requirements for accessing the CarrierService resource
To access the CarrierService resource, add the
permission to your app's requested scopes. For more information, see API access scopes.Your app's request to create a carrier service will fail unless the store installing your carrier service meets one of the following requirements:
- It's on the Advanced Shopify plan or higher.
- It's on the Shopify plan with yearly billing, or the carrier service feature has been added to the store for a monthly fee. For more information, contact Shopify Support.
- It's a development store.
NoteIf a store changes its Shopify plan, then the store's association with a carrier service is deactivated if the store no long meets one of the requirements above.
Providing shipping rates to Shopify
When adding a carrier service to a store, you need to provide a POST endpoint rooted in the
property where Shopify can retrieve applicable shipping rates. The callback URL should be a public endpoint that expects these requests from Shopify.Example shipping rate request sent to a carrier service
{"rate": {"origin": {"country": "CA","postal_code": "K2P1L4","province": "ON","city": "Ottawa","name": null,"address1": "150 Elgin St.","address2": "","address3": null,"phone": null,"fax": null,"email": null,"address_type": null,"company_name": "Jamie D's Emporium"},"destination": {"country": "CA","postal_code": "K1M1M4","province": "ON","city": "Ottawa","name": "Bob Norman","address1": "24 Sussex Dr.","address2": "","address3": null,"phone": null,"fax": null,"email": null,"address_type": null,"company_name": null},"items": [{"name": "Short Sleeve T-Shirt","sku": "","quantity": 1,"grams": 1000,"price": 1999,"vendor": "Jamie D's Emporium","requires_shipping": true,"taxable": true,"fulfillment_service": "manual","properties": null,"product_id": 48447225880,"variant_id": 258644705304}],"currency": "USD","locale": "en"}}Example response
{"rates": [{"service_name": "canadapost-overnight","service_code": "ON","total_price": "1295","description": "This is the fastest option by far","currency": "CAD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"},{"service_name": "fedex-2dayground","service_code": "2D","total_price": "2934","currency": "USD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"},{"service_name": "fedex-priorityovernight","service_code": "1D","total_price": "3587","currency": "USD","min_delivery_date": "2013-04-12 14:48:45 -0400","max_delivery_date": "2013-04-12 14:48:45 -0400"}]}The
address3,fax,, andfields are returned by specific ActiveShipping providers. For API-created carrier services, you should use only the following shipping address fields:address1address2cityzipprovincecountry
Other values remain as
nulland are not sent to the callback URL.Response fields
When Shopify requests shipping rates using your callback URL, the response object
ratesmust be a JSON array of objects with the following fields. Required fields must be included in the response for the carrier service integration to work properly.Field Required Description Yes The name of the rate, which customers see at checkout. For example: Expedited Mail.descriptionYes A description of the rate, which customers see at checkout. For example: Includes tracking and insurance.Yes A unique code associated with the rate. For example: .currencyYes The currency of the shipping rate. Yes The total price expressed in subunits. If the currency doesn't use subunits, then the value must be multiplied by 100. For example: for 5.00 CAD,for 1000 JPY.No Whether the customer must provide a phone number at checkout. No The earliest delivery date for the displayed rate. No The latest delivery date for the displayed rate to still be valid. Special conditions
- To indicate that this carrier service cannot handle this shipping request, return an empty array and any successful (20x) HTTP code.
- To force backup rates instead, return a 40x or 50x HTTP code with any content. A good choice is the regular 404 Not Found code.
- Redirects (30x codes) will only be followed for the same domain as the original callback URL. Attempting to redirect to a different domain will trigger backup rates.
- There is no retry mechanism. The response must be successful on the first try, within the time budget listed below. Timeouts or errors will trigger backup rates.
Response Timeouts
The read timeout for rate requests are dynamic, based on the number of requests per minute (RPM). These limits are applied to each shop-app pair. The timeout values are as follows.
RPM Range Timeout Under 1500 10s 1500 to 3000 5s Over 3000 3s NoteThese values are upper limits and should not be interpretted as a goal to develop towards. Shopify is constantly evaluating the performance of the platform and working towards improving resilience as well as app capabilities. As such, these numbers may be adjusted outside of our normal versioning timelines.
Server-side caching of requests
Shopify provides server-side caching to reduce the number of requests it makes. Any shipping rate request that identically matches the following fields will be retrieved from Shopify's cache of the initial response:
- variant IDs
- default shipping box weight and dimensions
- variant quantities
- carrier service ID
- origin address
- destination address
- item weights and signatures
If any of these fields differ, or if the cache has expired since the original request, then new shipping rates are requested. The cache expires 15 minutes after rates are successfully returned. If an error occurs, then the cache expires after 30 seconds.
- •OBJECT
The country code and whether the country is a part of the 'Rest Of World' shipping zone.
- Anchor to DeliveryCountryCodesOrRestOfWorld.countryCodesDelivery•OBJECT
Country Codes Or Rest Of World. country Codes The list of country codes and information whether the countries are a part of the 'Rest Of World' shipping zone.
- •INPUT OBJECT
The input fields to specify a country.
- •OBJECT
The shipping destinations where the discount can be applied.
- •INPUT OBJECT
The input fields for a list of countries to add or remove from the free shipping discount.
- •INPUT OBJECT
The input fields for a list of countries to add or remove from the free shipping discount.
- •ARGUMENT
An order that a merchant creates on behalf of a customer. Draft orders are useful for merchants that need to do the following tasks:
- Create new orders for sales made by phone, in person, by chat, or elsewhere. When a merchant accepts payment for a draft order, an order is created.
- Send invoices to customers to pay with a secure checkout link.
- Use custom items to represent additional costs or products that aren't displayed in a shop's inventory.
- Re-create orders manually from active sales channels.
- Sell products at discount or wholesale rates.
- Take pre-orders.
For draft orders in multiple currencies
is the source of truth for what a customer is going to be charged andis an estimate of what the merchant might receive in their shop currency.Caution: Only use this data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.
Draft orders created on or after April 1, 2025 will be automatically purged after one year of inactivity.
- •ARGUMENT
An order that a merchant creates on behalf of a customer. Draft orders are useful for merchants that need to do the following tasks:
- Create new orders for sales made by phone, in person, by chat, or elsewhere. When a merchant accepts payment for a draft order, an order is created.
- Send invoices to customers to pay with a secure checkout link.
- Use custom items to represent additional costs or products that aren't displayed in a shop's inventory.
- Re-create orders manually from active sales channels.
- Sell products at discount or wholesale rates.
- Take pre-orders.
For draft orders in multiple currencies
is the source of truth for what a customer is going to be charged andis an estimate of what the merchant might receive in their shop currency.Caution: Only use this data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.
Draft orders created on or after April 1, 2025 will be automatically purged after one year of inactivity.
- Anchor to DraftOrderAvailableDeliveryOptionsInput.marketRegionCountryCodeDraft•INPUT OBJECT
Order Available Delivery Options Input. market Region Country Code The input fields used to determine available delivery options for a draft order.
- •INPUT OBJECT
The input fields used to create or update a draft order.
- •OBJECT
The duty details for a line item.
- •OBJECT
The fulfillment order's assigned location. This is the location where the fulfillment is expected to happen.
The fulfillment order's assigned location might change in the following cases:
The fulfillment order has been entirely moved to a new location. For example, the fulfillmentOrderMove mutation has been called, and you see the original fulfillment order in the movedFulfillmentOrder field within the mutation's response.
Work on the fulfillment order has not yet begun, which means that the fulfillment order has the OPEN, SCHEDULED, or ON_HOLD status, and the shop's location properties might be undergoing edits (for example, in the Shopify admin).
If the fulfillmentOrderMove mutation has moved the fulfillment order's line items to a new location, but hasn't moved the fulfillment order instance itself, then the original fulfillment order's assigned location doesn't change. This happens if the fulfillment order is being split during the move, or if all line items can be moved to an existing fulfillment order at a new location.
Once the fulfillment order has been taken into work or canceled, which means that the fulfillment order has the IN_PROGRESS, CLOSED, CANCELLED, or INCOMPLETE status,
acts as a snapshot of the shop's location content. Up-to-date shop's location data may be queried through location connection.- •OBJECT
Represents the destination where the items should be sent upon fulfillment.
- Anchor to HasLocalizationExtensions.localizationExtensionsHas•ARGUMENT
Localization Extensions. localization Extensions Localization extensions associated with the specified resource. For example, the tax id for government invoice.
- •ARGUMENT
Localized fields associated with the specified resource.
- •OBJECT
Represents the goods available to be shipped to a customer. It holds essential information about the goods, including SKU and whether it is tracked. Learn more about the relationships between inventory objects.
- •INPUT OBJECT
The input fields for an inventory item.
- •OBJECT
Represents the value captured by a localization extension. Localization extensions are additional fields required by certain countries on international orders. For example, some countries require additional fields for customs information or tax identification numbers.
- •OBJECT
Represents the value captured by a localized field. Localized fields are additional fields required by certain countries on international orders. For example, some countries require additional fields for customs information or tax identification numbers.
- •INPUT OBJECT
The input fields to use to specify the address while adding a location.
- •INPUT OBJECT
The input fields to use to edit the address of a location.
- •OBJECT
Represents a suggested address for a location.
- •OBJECT
Represents a customer mailing address.
For example, a customer's default address and an order's billing address are both mailling addresses.
- •INPUT OBJECT
The input fields to create or update a mailing address.
- •INPUT OBJECT
The input fields to specify a region condition.
- •OBJECT
A country which comprises a market.
- •INPUT OBJECT
The input fields for creating a market region with exactly one required option.
- •OBJECT
A score that represents the shop's ability to deliver on time to a particular country. The score is a value between 0 and 1.
- •ARGUMENT
The
Orderobject represents a customer's request to purchase one or more products from a store. Use theOrderobject to handle the complete purchase lifecycle from checkout to fulfillment.Use the
Orderobject when you need to:- Display order details on customer account pages or admin dashboards.
- Create orders for phone sales, wholesale customers, or subscription services.
- Update order information like shipping addresses, notes, or fulfillment status.
- Process returns, exchanges, and partial refunds.
- Generate invoices, receipts, and shipping labels.
The
Orderobject serves as the central hub connecting customer information, product details, payment processing, and fulfillment data within the GraphQL Admin API schema.NoteOnly the last 60 days' worth of orders from a store are accessible from the
Orderobject by default. If you want to access older records, then you need to request access to all orders. If your app is granted access, then you can add the,, andscopes.CautionOnly use orders data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.
Learn more about building apps for orders and fulfillment.
- •ARGUMENT
The
Orderobject represents a customer's request to purchase one or more products from a store. Use theOrderobject to handle the complete purchase lifecycle from checkout to fulfillment.Use the
Orderobject when you need to:- Display order details on customer account pages or admin dashboards.
- Create orders for phone sales, wholesale customers, or subscription services.
- Update order information like shipping addresses, notes, or fulfillment status.
- Process returns, exchanges, and partial refunds.
- Generate invoices, receipts, and shipping labels.
The
Orderobject serves as the central hub connecting customer information, product details, payment processing, and fulfillment data within the GraphQL Admin API schema.NoteOnly the last 60 days' worth of orders from a store are accessible from the
Orderobject by default. If you want to access older records, then you need to request access to all orders. If your app is granted access, then you can add the,, andscopes.CautionOnly use orders data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.
Learn more about building apps for orders and fulfillment.
- Anchor to PriceRuleShippingLineEntitlements.countryCodesPrice•OBJECT
Rule Shipping Line Entitlements. country Codes The shipping lines to which the price rule applies to.
- •OBJECT
A product feed.
- •INPUT OBJECT
The input fields required to create a product feed.
- •OBJECT
Represents a collection of general settings and information about the shop.
- •OBJECT
An address for a shop.
- •OBJECT
A bank account that can receive payouts.
- •ARGUMENT
The schema's entry-point for queries. This acts as the public, top-level API from which all queries must start.
- •ARGUMENT
The schema's entry-point for queries. This acts as the public, top-level API from which all queries must start.
Deprecated fields
- •OBJECTDeprecated
- •QUERYDeprecated