API FAQ - Please check here before posting! Updated: Aug 2022
FREQUENTLY ASKED QUESTIONS
Updated August 23rd, 2022
I’m trying to send a PUT/POST request to ‘x’ endpoint, but I’m receiving a login screen/URL as my response instead of my intended result. Why is this happening?
Shopify does not allow for cookies to be passed when performing requests with basic HTTP authentication. Check your client to make sure that you are not including cookies in your requests.
How is the API process affected by Admin configurations? Can I expect the API to respect all of the product/collection/inventory/etc related settings that I have in the Admin?
The API, by default, will generally override any Admin settings related to the action you are trying to process. This means you can process orders for items you have 0 inventory for, even if the Admin configuration is set to "Do not allow overselling", you can create orders and assign customers that have a shipping address for which you have no Admin-set shipping rates, or you can apply a discount to an order for a customer who would not normally be eligible for said discount. As long as the payload is formatted correctly, the API will process it without validating it against your shop's configuration first. It is a best practice to check for any product/customer/inventory settings that need to be respected first before processing a new action, if necessary.
I’m trying to send a request to the API, but I’m receiving a 422/Unprocessable Entity error. What does that mean? How do I avoid it?
An ‘Unprocessable Entity” error means that your payload includes data that is not compatible with the endpoint you are trying to interact with. Our API has strict requirements in terms of what data can be passed, and successful interactions will require careful formatting of any request body. Examples of things that would cause a 422 include:
Trying to write a read-only field
Entering an integer where a string is expected (or boolean, etc)
Missing permissions/scopes for the operation being performed
General formatting issues (commas, parenthesis, etc)
Missing fields/values - some operations require a field to be specified (like an object id) in either the payload or the endpoint URL. Example: missing fulfillmentOrder id when performing a fulfillment action on an order with multiple fulfillmentOrders
When encountering this error, you will need to carefully reference your payload data against our documentation and ensure that all fields are correctly formatted before trying again.
I've setup a fulfillment service via API, however I'm running into some trouble. What can I look out for when trying to fulfill via API?
There are a few important considerations when operating as a fulfillment service via API. First is that any given app can only access fulfillments that are scoped to the app in question - this means if the merchant has not sent a request to your fulfillment service to process the fulfillment, you will not have the necessary access to mark the order as fulfilled. Next, it is important to account for specific products that have unique fulfillment configurations. There can be products that are set to be fulfilled by Amazon or other fulfillment services, which needs to be considered when processing fulfillments on orders with these items. They may cause 422 errors if your payload body assumes that all order line items are configured the same way. Lastly, it can be useful to understand how fulfillmentOrder and fulfillment objects interact with one another, as well as how your app will navigate them. The Admin may automatically cause an order to split into multiple fulfillmentOrders as opposed to just one, depending on the line items being sold or other shop configurations. This can have an impact on your app's fulfillment process, if you are expecting to be able to fulfill the entire order with a single fulfillment payload.
I want to publish my product on all channels, but my only options are Online Store and POS. Why can’t I publish on other channels?
Sales Channel publications are scoped to the app that manages that Sales Channel in question. Private apps are given default access to POS and Online Store at this time.
I am trying to request a list of my webhooks, but some are missing in the response OR I am trying to modify a specific webhook by id, but I can’t access it. Why is that?
Similar to Sales Channels mentioned above, webhooks are specifically scoped to the app that created them. If you try to make a call for a webhook that was created by a different app, you will not be able to access or modify that data. Get requests can be used to verify which webhooks your app is responsible for managing.
I’m encountering a 500 Internal Server Error when performing my operation. What should I do?
500 Server Errors are typically the result of a server side timeout, but can occur for a variety of reasons, and tend to be slightly more common with Bulk Operations vs regular Operations. In the event that you encounter a 500 level error in your interaction with the API, please make a post describing your interaction with the following info:
Date/Time of error
Endpoint utilized
X-Request-ID (can be found in the response headers)
Special note: 500 errors can pop up when attempting to access a resource via metafieldDefinitions that you don't have the necessary permissions to read/write. If you are requesting metafieldDefinitions, citing a specific "ownerType", and are running into a 500 error, make sure your app has read/write permissions on whatever ownerType you are requesting first.
I’m randomly encountering 503 errors when interacting with the API. The errors are intermittent and I don’t understand why. What should I do?
API interactions are subject to rate limiting and throttling. 503 errors occur when requests start being dropped due to excessive volume. You will need to reduce call volume to avoid encountering 503 errors for your app. Best practices related to rate limits can be found HERE
I want to create orders and process payments. Can I do this by interacting with the Orders and Transactions endpoints via a private app?
An important thing to keep in mind is that while you can create orders and transaction entries via those endpoints, these operations will not result in any form of payment processing. Payment processing needs to occur via a payment gateway in some manner, whether it be entirely external to Shopify, or via a Sales Channel/Checkout API configuration. More information on creating a Sales Channel can be found HERE.
Please bear in mind also that as of April 30, 2022, new merchants can no longer install legacy Hosted Payment SDK (HPSDK) integrations. All new payment apps must use Shopify's Payments App API which does not allow for interaction between the Payments App API and other Shopify APIs. More information can be found here on these changes.
I need to gather Customer IDs from the new CustomerSegmentMember object. There is no explicit reference to Customer ID, so is there an easy way for me to pull that information?
The Customer object and the CustomerSegmentObject both use the same global ids when referring to customers. If you have a Customer with id "123456789", then they will have a CustomerSegmentMember id of "123456789" to match. If you require Customer IDs, you can pull the ID field from CustomerSegmentMember to get "gid://shopify/CustomerSegmentMember/123456789" and change the object name as appropriate.
I’m having an issue with this component of the Storefront API/I’m having trouble with this particular Liquid/Theme component/I have a question about Subscriptions…
While we encourage diverse and open discussion related to development on this board, we kindly request that Storefront API and Liquid related topics be directed towards their respective boards:
I’ve developed my app and I’m currently experiencing issues or have questions related to the approval process…
We kindly request that any inquiries or discussions related to app approval be directed to either the Partner Discussion board, or directed to a member of our Partner Support team via a direct support interaction.
When I perform a GET to orders.json for orders that are older than 60 days, I don’t receive those orders in my response. I’m also missing some of the orders that are within that 60 day time period. Why is this happening?
With the basic read_orders scope, Shopify will return orders up to a maximum of 60 days old, and among those orders, only those with the status of “Open” will be included in the response. Partners must request the read_all_orders_scope to read greater than 60 days of orders, and also the parameter “status=any” to retrieve any archived or cancelled orders. More information on this process can be found HERE
I'm trying to create orders on my development store via API, however I'm encountering errors like "checkout unavailable". What is happening?
Development stores must use the Bogus Gateway or Shopify Payments in test mode in order to process test orders. Attempts to process orders that utilize other gateways will not interact with the checkout correctly, and will result in errors related to the checkout being unavailable.
I'm receiving warnings about deprecation/A merchant with my app is seeing a flag in their admin home about deprecation and needing to update my app. What's this all about?
Shopify updates the API on a regular basis, with new API versions coming out on a 3 month rotation. API versions have a 12 month lifespan, after which point a given version will expire, along with any deprecated features associated with that version that were not ported over to the next version in line. We strongly encourage API users to review the following materials in order to learn about our API health best practices:
https://shopify.dev/api/usage/versioning
https://shopify.dev/api/usage/versioning/api-health
https://shopify.dev/api/usage/versioning/private-apps
https://shopify.engineering/shipit-presents-shopify-api-health-report
What is the difference between all the tokens and keys provided when creating apps?
- api key: A public unique identifier for your app.
- shared secret: A secret shared between Shopify and your app, used for authentication. Used by Shopify to sign webhooks and other requests.
- access token: Another secret, but a new one is generated every time a new person installs your app. Each one is used for authentication of regular API calls to a particular shop.
- password: Like an access token, but for "private apps" created in a shop's admin, and intended to be used with Basic Auth.
- refresh token: A temporary secret token which can be used along with a shared secret to retrieve access tokens for any shop that has previously granted access to your app. Generated from the Partners area UI as part of a credential rotation process.
I have feedback related to a developer/API doc. Where/how do I submit feedback or request changes/updates?
At the bottom of each developer doc, you will find a feedback prompt that looks like:
Selecting "No" will expand a feedback prompt, where you can provide any feedback or update requests related to the document you are viewing. We encourage you to use these prompts, as we are constantly working to improve the quality and depth of our developer documentation.
I've heard that the Fulfillment API is being deprecated. Where can I get more information about this?
Effective July 1st, 2022 the Legacy Fulfillment API has been deprecated. That said, apps will have until the 2023-04 release to migrate away from the deprecated API and use the new Fulfillment Orders API Please see the fulfillment orders migration document here if your app is affected or here for more general information on Fulfillment Orders
SUGGESTED LEARNING AND TESTING RESOURCES
https://www.shopify.com/nz/partners/blog/shopify-graphql-learning-kit
https://documenter.getpostman.com/view/3800273/SWLk55pF#d4808f65-12da-4e24-b321-3df8a7063ae9
https://shopify.dev/api/release-notes
