Setting up order placement

There are two general methods for checking out with Rye, but our recommendation for gifting platforms is to use backend ordering. This method allows you to charge shoppers for the gift and place the order on their behalf using your own contact details, which prevents the gifter from receiving any order-related emails and ensures that the recipient’s personal information is kept private.

Good to know: You can read up on both checkout methods here. The rest of this guide will focus on getting you set up with backend ordering.

Below we have outlined the high-level steps involved in placing orders. The simplest way of working with Rye involves using our API end-to-end, which is possible in situations where you are only selling products through Rye. If you have a pre-existing checkout system with products from other sources, then it is still possible to slot Rye in but you’ll need to manage your own cart and split up the order into Rye and non-Rye products.


Keep track of the shopping cart

Rye has a native shopping cart system that you can use to manage the checkout experience end-to-end in cases where all of your gifts are being sold through Rye. Our tutorial will help acquaint you with using the createCart and addCartItems mutations for this purpose. Note that you will want to call updateCartBuyerIdentity with the recipient’s information, as the buyer identity is used for the shipping address.


Calculate the price

On your backend you will need to calculate the price of the cart for the gifter. The Cart object returned from getCart contains a queryable cost field which you can return to your frontend for display purposes, and for charging the gifter.


Charge the gifter

Once the gifter has indicated their payment intent, you will capture their payment method and charge them. If you already have a payment gateway in place then you can continue using that, but otherwise we recommend using Stripe for this purpose as it is easy to integrate.


Place the order using the Rye API

Once the gifter has been charged, you will have funds available to place the order through Rye. On your backend you should hit the submitCart mutation to place the order. This mutation expects a token input, which should be a payment token for a card owned by your business.


Handle the post-checkout flow

From here Rye sends out webhooks whenever an order is placed, updated, or cancelled. You can use these webhooks to handle errors, or send out post-purchase notifications to the gifter and/or recipient.

We have a detailed step-by-step guide for creating carts and submitting orders on the backend which you can find here.

Developer considerations

Why backend ordering?

Rye Pay ordering requires the use of JWT authentication, which grants the frontend access to Rye APIs. A technically-minded user would be able to use this access to fetch the Rye shopping cart and see the recipient’s shipping information. By moving all Rye API calls into your backend system, it is possible to prevent this information from being exposed to the gifter.

Checkout flows

The specific details of your checkout flow will depend on whether you are exclusively transacting through the Rye API, or if you are mixing Rye products with products from other sources. There are also different considerations for checking out with a single item versus multiple items.

Single-item checkout

  • Start by identifying which products come from Rye and which products already exist in your current database.
    • You’ll need a way of distinguishing between the two programatically. A source field on your product objects can work well for this.
  • At the time of checkout, branch depending on the source of the product:
    • For products that come from outside Rye: Continue with your existing flow.
    • For products that come from Rye: Adjust your checkout flow to ask for additional information that is required by Rye to perform a successful checkout.

Multi-item checkout

Just like for single-item checkout, you will need a way of distinguishing between Rye products and non-Rye products. After you have done this, there are three cases to deal with during checkout depending on the contents of the cart:

  • Only Rye products in a cart:
    • Adjust your checkout flow to ask for additional information that is required by Rye to perform a successful checkout.
  • Only your products in a cart:
    • Continue with your existing flow.
  • Mix of Rye and your products in a cart:
    • Collect all information that is required by Rye.
    • During the payment step, complete the payment for Rye items via a new backend endpoint in your system which calls out to the submitCart mutation.

Post-checkout experience

Rye supports order cancellations, refunds, and returns. Please review instructions in your console and the relevant documentation.


  • Is there any marketplace, such as Shopify or Amazon, where you can include a note with the order or offer a gift-wrap option?

    We currently don’t provide the option to add notes, but we can verify if it’s feasible.