Appendix
FAQs
Quick answers to common development questions.
API usage and limits
What are the usage limits for API requests?
Our API currently enforces an overall request limit of 300 products. If your development needs exceed this threshold, we’re here to help. Please request an increase by contacting us.How quickly are requested products available for querying?
Product availability is typically instantaneous for requests of fewer than 100 products. For larger batches, please allow a few minutes for processing. If you encounter any delays or issues, do not hesitate to contact our support team.Adding products/supported products
Which products are supported by the Sell Anything API?
The Sell Anything API currently supports any product from Amazon Canada/US and Shopify platforms.Do we need to add a product to Rye before we can query for its product data?
Yes, Rye needs to know about a product before it can be used - this can be accomplished either from a Shopify store installing the Rye Shopify App, explicitly requesting a Shopify Store by URL, or explicitly requesting a Product by URL.When a vendor installs the Rye App, do they choose which items to offer on our marketplace, or can we access anything from their store once the Rye app is installed?
By default, all products are imported into Rye. However, within the app, you can choose to publish collections or individual products to a specific sales channel. Additionally, when creating new products, there is a checkbox option to publish them to sales apps like Rye.Is the productsByDomainV2 endpoint non-functional when the store is not integrated?
It should work if you requested the store through the requestStoreByURL.
Currently, Rye performs variant lookups using the Shopify variant ID. Is there a method to look up the variant based on a store and SKU, without using the ID?
You have the option to utilize the Raw Shopify API for any lookup requirements. If you determine the specific query you wish to execute, we can assist and include it in the allowlist.For Sell Anything API, does Rye provide webhooks for product updates? For instance, if we request a store or product and subsequently offer the product within our service, we’d like to be notified when that product goes out of stock or when its price changes, among other relevant updates.
We anticipate adding webhooks for the Sell Anything API to our roadmap, with an expected arrival around mid-March.Is the “switch to staging” feature intended for your internal developers or for public use?
It is intended for public use.I’ve been attempting to configure the Rye Medusa backend on Railway. I cloned the GitHub repository, deployed it, and configured the environment variables as instructed. However, upon deployment, the server encounters an error upon startup. It seems to retry every 2-3 minutes, but after 10-15 minutes, it crashes.
Unfortunately, that might not establish a solid foundation for success, particularly if you intend to enhance the marketplace functionality. It’s likely that additional customizations will be necessary. We recommend initially setting it up entirely on your local environment (instead of using Railway). This way, you can understand the impact of the environment variables on the project and delve into some of the custom TypeScript. The code isn’t overly complex, and ChatGPT is a valuable resource for explaining it. Once you’ve set it up locally, the process of porting it to Railway will be much smoother.How can we retrieve the unit amount in cents as a whole integer for product variants?
You can obtain the cents value for variants by querying the field priceCents.Can we utilize the Sell Anything API to retrieve product data independently and subsequently employ the place order endpoint to complete the order via Rye?
Yes. You’ll still have to “request” the product initially, but afterward, you can add them to the cart using the product IDs.Products on Shopify
How can I identify if a store is powered by Shopify?
You can use the free Wappalyzer chrome extension to identify if individual stores use Shopify. Alternatively, you can head over to Storeleads to search for Shopify stores in bulk. Here is a list of the top 10,000 stores on ShopifyDoes Rye have all of Shopify retailers covered?
Yes, our Sell Anything API works on almost all Shopify retailers (the few exceptions are some login-only stores, private stores, etc.).Are there plans to allow us to query by brand?
It’s not on the roadmap for us at the moment, but we can check to see if it’s possible.Is there a field to obtain the overall rating of a product for Shopify?
We currently lack that feature, but we can include it in our future development plans. At present, we only receive raw data from the native Shopify stores and have not implemented aggregation.If we integrate an entire Shopify store into our Rye inventory, will our inventory automatically synchronize with any new products added by that store, or do we need to update it manually?
The newly added products are included automatically.A user has mentioned difficulties connecting their store, citing they are on the Shopify starter plan. Is it a scenario that is not supported by your system?
It appears that the user won’t be able to install the app, and this is determined by Shopify. It seems they are not permitting this without an upgraded subscription.Can you share a URL for an integrated Shopify store that is accessible on the staging environment?
Currently, there isn’t such link for staging. However, we can manually facilitate this functionality for your test store. If you connect a store to production, we can enable it in the staging environment once you provide us with the store’s name.Once the Shopify integration is completed, what process will we follow to make orders through it? Can you describe the envisioned workflow?
It’s currently planned for March, but we haven’t finalized all the features for it yet. Essentially, it will allow you to add a product via URL, and when orders are placed on the Shopify frontend, it will trigger the Rye API for fulfillment.We were curious about how orders will be processed through a Shopify store. How will the products in Shopify be linked to Rye?
Currently, we don’t have that feature yet. You’ll need to establish the mapping on your side and instruct Rye to place orders via the API. We anticipate having a Shopify app capable of handling this by the end of March.We’ve already established the framework to retrieve product data from Shopify stores and integrate it into a Shopify backend. Will we be able to link these existing products to Rye for order fulfillment?
Certainly, once a user completes a payment on your Shopify store, you’ll need to develop a mechanism to transmit the order specifics to us through the API.Do you send out webhook notifications if an item is out of stock even when inventory tracking isn’t on?
We retain the inventory count that Shopify has previously recorded for the item, in line with Shopify’s default behavior. We haven’t made significant changes to this process. However, we do include the inventory policy in the webhook notifications, which indicates if the item can still be sold despite the inventory count. For more information, see the Shopify inventory policy documentation To determine if an item should be considered “in stock,” check the inventory policy in the webhook or the API response’s available flag, particularly if the inventory count is negative.Products on Amazon
Do you have a timeline for when it’ll be possible to query all products from an Amazon store through the Rye API?
For Amazon, we don’t get products by stores. Queries are basically for products on the platform as a whole.Payments and ordering
How should I set up payments?
When integrating with Rye, developers should capture payments with their own payment processor (for example, Stripe) and then call Rye to place the order once the payment succeeds.After submitting a cart, the order status did not update instantly. Do you have information on the average time it typically takes for a single order to be processed?
a. For Amazon orders, it is instant. b. For a Shopify order, the processing time varies depending on whether the order is with a merchant connected through Rye (instant) or through the Sell Anything API (asynchronous).We don’t always have the buyer’s email or phone number, can these fields be not required?
This field is mandatory, but you have the option to utilize a corporate email or phone number if preferred.Will the email or phone number be shared with the buyer?
Specifically for Amazon, it’s important to note that email and phone number information is not shared, and Amazon does not send receipts.If our store mistakenly displays the incorrect price, and a user creates a Rye cart and proceeds to checkout with the incorrect price, would Rye detect the mismatch or stale price and fail to process the order in such a scenario?
You need to ensure that your price is updated. Upon submitting an order, we retrieve the latest price for a product.Regarding the phone property within the BuyerIdentity objects set on Rye Carts during the Checkout process, is it crucial or mandatory for this field to be populated with the shopper’s actual phone number?
We require a valid phone number, and it doesn’t necessarily have to be the end shopper’s; a corporate number will suffice. Currently, we enforce strictness in accepting phone numbers due to the mandatory phone number validation check required by Shopify in certain stores. We can certainly reconsider this requirement in the coming months and potentially be more selective in when we demand it.What occurs when a payment fails because of insufficient funds on the card?
In this situation, anticipate receiving aPAYMENT_FAILED error response when utilizing the submitCart mutation.
How does the process of reattempting the transaction work after adding funds to the card? Can the same cart still be submitted?
At this stage, the cart has been marked as already submitted, so you would be required to generate a new cart.How do I obtain the request ID for a cart that has already been submitted?
If you have the cart ID in scope, you should utilize the checkoutByCartID queryHow can we go about applying coupons when they are available?
Coupons are not supported through the API.Will webhooks include a CompletePaymentChallenge object when a challenge is necessary, or would it be necessary to utilize orderByID to retrieve the challenge URL?
Indeed, you must utilize the orderById method to obtain that information.
Our system triggers the orderByID immediately following the submitCart action. Would this procedure result in obtaining the challenge URL? Is there a possibility of a delay in processing the submission, which could result in the URL not being generated promptly? Additionally, does a webhook exist to notify us when the shipment has successfully reached the user’s destination, similar to an “order completed” event?
The challenge may occur within a short timeframe, typically not too long. Currently, we don’t send a webhook for delivery confirmation, only the tracking information.
When we submit a cart, we receive various orders from multiple stores, but we lack the information on which order corresponds to which store.
A simpler solution in this scenario would be to divide the orders into separate API submission requests. Alternatively, you could retrieve the store names or examine the cart lines associated with each store.Shouldn’t the domain of the store and the items in the order be incorporated into the order structure?
You have the option to utilize this API here for retrieving comprehensive order details, which encompass the order items.Is there a method to verify the authenticity of the incoming webhook request, such as using a signing key or similar mechanism?
It’s currently on our roadmap, but it’s not yet available at this time.We’ve noticed a digital product in the test data that’s causing issues with retrieving the correct order total. Could you please confirm if your platform supports digital products?
Rye requires a valid selected shipping option when submitting a cart, which means digital products are currently not supported. While they are on the roadmap for future implementation, for now, it’s advisable to concentrate on physical products exclusively.Do you have any idea about the proportion of Amazon products and Shopify stores that offer international shipping? Based on what I’ve observed, it appears that a significant number of them provide global shipping services.
For Amazon, our current support is limited to North America only. As for Shopify, it depends on the settings configured by each individual shop. Note that we can’t ship orders to the following countries that require a personal ID number for the recipient: Brazil, Italy, Spain, China, Russia, South Korea, and Turkey.How are currency conversions handled? If a merchant lists an item in GBP, will the customer be billed in GBP, or will they be charged in USD based on the current currency conversion rate?
We apply charges in USD according to the conversion rate.How does tax collection work for developers using Rye?
The developer is responsible for collecting sales taxes from the end user. Rye then pays the merchant, who handles tax remittance to the relevant authorities. If the seller has a valid reseller certificate, they may qualify for tax exemption, in which case taxes would not be collected at checkout.Amazon ordering
I see that you don’t return the Amazon Order ID after it’s placed?
We have our own order ID which is associated with the corresponding Amazon order ID.Does your API support Prime orders?
Yes, our endpoint is set to default to Prime shipping.Is it possible to get amazon_order_id, buy_price, tracking information using api call?
For now, they are only available by webhook.Is it easy to ingest Amazon apparel catalog?
Our API right now doesn’t actually have categorization, but should be pretty easy to get a 1 off script to do what you need to do. Rainforest API is a great tool to grab products from a category: Rainforest API, and then all you have to do is run the ASINs returned there into our API to be able to do native checkout with our API.Is it possible to place simultaneous orders on a single Amazon account, and if so, are there any restrictions or limits in place? If parallel processing is feasible, is there are any limitations on your end?
There shouldn’t be any obstacles to its functionality, but we encourage you to conduct tests. If any challenges arise during testing, we are ready to collaborate with you to find solutions. It’s important to note that unlike Zinc, we don’t employ scraping methods when sending orders. Our approach is fully programmatic. Although there might be initial rate limits imposed by Amazon, we can adjust those limits to ensure that your scale is efficiently processed. Therefore, there’s no necessity to perform actions in parallel.I couldn’t find an endpoint or a method in the console to add our own Amazon account. How can we go about this process?
We need to convert your account to support the addition of your own Amazon account. After that, you can visit console.rye.com and follow the OAuth flow to connect your Amazon account.We prefer to use our own Amazon accounts. Therefore, we require a method to access the Amazon Order ID. Kindly provide guidance on how we can achieve this.
We currently do not provide access to the Amazon Order ID, but we can incorporate this feature if it is required.I observed that the schema does not include support for tracking information or retrieving the Amazon Order ID.
The tracking information and Amazon Order ID are not present in the event schema. However, we can make them accessible for you under the TRACKING_OBTAINED event. This event is triggered when we obtain that information. While we don’t expose it in the query itself, it is available in the actual webhook payload.Can you also make the Amazon Order ID accessible in the Order Placed Event?
Certainly, we have the capability to do that.Do you facilitate shipping orders to international destinations on Amazon?
For the time being, we recommend focusing on products and buyers within the United States. We’ll need to assess and plan how to effectively support other countries.I’ve just finalized three orders for Amazon products in the production environment, but I haven’t received any confirmation emails from Amazon regarding these orders.
Regarding Amazon, only webhook updates are available; emails are not sent. This is because Amazon confirmation emails necessitate logging into an Amazon Business account. The suggestion here is to send your own emails, unlike the approach taken with Shopify.If we opt to send our own emails, we must ensure that all the necessary information is included within the email. Does the webhook furnish all the required details?
The webhook will contain arequestId, which can be utilized to inquire about the order for any supplementary information you might require.
Can we obtain the Amazon tracking URL through the orderByID endpoint or any other method when the order is placed (before it’s shipped)? Our tracking conversion service requires a valid tracking URL to convert tracking, so we need to ensure we can provide this information.
Since we only receive the tracking number and lack the means to generate the tracking URL from it, there are components in that URL, notably the itemId, that we are unable to retrieve.Cart management
When utilizing the createCart mutation, is the resulting cart created within Amazon, or is the cart data derived from an internal Rye cart?
The data is from internal Rye cart.Why is the cost field returning as null in the response of a cart creation API request?
Once you set the buyer identity for the cart, a non-null value for the cost field will be returned in the response.What is the optimal approach for managing a user’s cart?
The suggested method is as follows: Only create a Rye cart when a user tries to add an item to the cart, and store the cartID on the client side for all other cart-related operations. Additionally, to access shipping options on the client side, the cart should have a buyer identity linked to it with some items. This implies that by the time you reach the shipping options stage, your Rye Cart should be prepared with all the necessary information. You can also save only the Rye cartIDs in your database for post-checkout experiences, along with the orderIDs. This will be beneficial for debugging and checking the status of carts, such as whether they are completed or abandoned.In our testing phase, we noticed that the createCart mutation could have a latency of up to 20 seconds in the production environment. Although this has recently decreased to 1-2 seconds, can we have confidence that the latency will remain consistent when we deploy our integration to the live environment?
We’ve been implementing infrastructure enhancements to improve performance. However, it’s worth noting that depending on factors such as the product, cart size, and demand, there may still be occasional spikes in latency.Does Rye make use of the Shopify checkout and cart, or does it employ its own system? How does this arrangement interact with Shopify’s transaction fee, or does it entirely circumvent it?
We indeed make use of Shopify checkout and cart. Regarding transaction fees, it’s the merchant who covers the transaction fee for Shopify, and developers are not responsible for this cost.Can we assume that the subtotal cost, total cost, and shipping cost in a CartResponse must be in the same currency, even if the prices of individual cart items are in different currencies?
It appears that the current behavior is as follows:
- If all the offers from the various stores linked to the cart share the same currency, the cart cost will be in that currency.
- If any of the offers have prices in different currencies, the cart cost defaults to USD.
I observed that the AmazonCartLine includes AmazonProducts, while the ShopifyCartLine contains ShopifyVariants.
- In cases where the Shopify item lacks variants, is there an automatic creation of a “base” variant?Each item in Shopify is essentially a variant; a product must have at least one variant. When a shopper makes a purchase, they are selecting a variant, which is why we necessitate the variant ID rather than the product ID.
-
Does the presence of the
AmazonProductin the cart specifically denote the item variant, or does it encompass the entire item itself?In Amazon, the product ID you’re buying directly corresponds to what you’re purchasing. Amazon doesn’t have the concept of variants; each variant in Amazon is treated as a distinct product. There is no overarching base product concept in this context.
If a Rye cart has been generated and submitted, trying to submit it again should consistently result in an error, correct?
Yes, that’s correct.Do you support cancellation requests via API?
The cancelOrder API request is currently only supported for Amazon orders. Shopify support is not available today, but on our roadmap. Note that can only cancel orders that have not been shipped yet.Order status and delivery updates
If webhook fails, do you retry until you get 200 status for webhook?
We don’t retry the webhooks at the moment.I see the webhook option, but is there a polling option as well?
You have the option to use theorderId endpoint to retrieve the order status and tracking information from the events field, if present. However, relying on webhooks is likely the most optimal and current method.
Is there an API call available for obtaining shipping method and the expected delivery date?
The estimated delivery that hasn’t been exposed via the API, we can explore options on how to provide it if necessary.We have successfully implemented the orderByID query on the backend. However, is there a method to obtain additional information about the events? As per the documentation, it currently provides only the ID and timestamp.
The ID within the events array corresponds to the webhook event ID that will be received and includes all the relevant data.Monetization and commissions
Do you work with any affiliate networks?
We leverage our integration with Skimlinks and Sovrn to generate affiliate commissions.Regarding the Sync API, is there a method to sync clients while maintaining their privacy within the Rye network? Some of our brands prefer to remain private and may not want their information shared across the entire network.
We might be able to address this scenario, but we’ll need to have a more in-depth discussion with the team if we haven’t already done so.What distinguishes the currentRatePercent from the commissionProposal?
This process is intended to operate as follows:- The developer submits a commission proposal to a merchant.
- The merchant reviews the proposal and decides whether to approve or reject it. During the review period, the proposal is accessible in the commissionProposal field.
- If approved, the proposal transitions to become the currentRatePercent, influencing subsequent orders.