Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

Attach shopper information

Good to know: This tutorial assumes you have a cart ID handy. If you do not have one, then please follow our "create a cart" guide and then come back once you have a cart ID.
By default, carts do not know where you want to ship the cart items to. The updateCartBuyerIdentity mutation can be used to attach shipping information to a cart, which will then let you retrieve shipping options and the final cart cost.

Tutorial

Step 1: Update cart buyer identity

mutation AttachBuyerIdentity {
  updateCartBuyerIdentity(
    input: {
      # NOTE: Replace this value with your own cart's identifier!
      id: "TgDZ0GvuqZkVlmdhm94f"
      buyerIdentity: {
        firstName: "John"
        lastName: "Doe"
        email: "john@rye.com"

        address1: "1460 Broadway"
        city: "New York City"
        provinceCode: "NY"
        countryCode: US
        postalCode: "10036"
      }
    }
  ) {
    cart {
      id
      cost {
        isEstimated
        shipping {
          currency
          displayValue
          value
        }
        total {
          currency
          displayValue
          value
        }
      }
    }
    errors {
      code
      message
    }
  }
}
Note that in this example, our shipping cost is US$0. This is because we have crossed the threshold for free shipping with Amazon, which at the time of writing is US$35 for domestic deliveries within the USA. If we were to remove some items from our cart with deleteCartItems and our cart price dropped below that threshold, we would see a non-zero shipping price.
If your provided address was invalid, then errors will be returned inside the top-level errors field on the cart. You can see what this looks like if we pass an invalid postal code inside our input:
mutation AttachBuyerIdentity {
  updateCartBuyerIdentity(
    input: {
      # NOTE: Replace this value with your own cart's identifier!
      id: "TgDZ0GvuqZkVlmdhm94f"
      buyerIdentity: {
        firstName: "John"
        lastName: "Doe"
        email: "john@rye.com"

        address1: "1460 Broadway"
        city: "New York City"
        provinceCode: "NY"
        countryCode: US
        postalCode: "1991559"
      }
    }
  ) {
    cart {
      id
    }
    errors {
      code
      message
    }
  }
}
All possible error codes here are documented on the CartErrorCode reference page. Error codes prefixed with BUYER_IDENTITY_ indicate an issue with the provided buyer identity, and if these are not resolved then checkout will fail.

Step 2: Inspect shipping options

After attaching a buyer identity, offers will be available from each store in your cart. You can fetch shipping options at the same time you attach buyer identity information by simply adjusting the selection set on your updateCartBuyerIdentity request:
mutation AttachBuyerIdentity {
  updateCartBuyerIdentity(
    input: {
      # ...
    }
  ) {
    cart {
      id
      # ...
      stores {
        ... on AmazonStore {
          store
          offer {
            shippingMethods {
              id
              label
              price {
                currency
                displayValue
                value
              }
            }
          }
        }
      }
    }
    errors {
      code
      message
    }
  }
}
This new query requests the store and offer fields on the AmazonStore object. If you are ordering from Shopify, then these fields also exist on the ShopifyStore object with a very similar structure.
The store field acts as a unique identifier for the store. A single Rye cart can contain cart items from multiple merchants at the same time, and the stores list lets you see how your cart items are broken up by store. In the case of a multi-store cart, each store will have its own shipping options available. Our example cart only needs to deal with a single store, which makes things slightly easier.
Good to know: The offer field is available through any API operation that returns a cart, including getCart. This is helpful if you forgot to request offer when you first attached buyer identity information.
Edge Case: If you receive an empty array for shippingMethods from a Shopify store, it may be because both of the following conditions are met:
  1. The store is configured with only third-party logistics (3PL) shipping methods, which are available through Shopify apps installed in the store (e.g., FedEx).
  2. The product in your cart is not published to the “Online Store” sales channel.
This limitation will be resolved once Shopify updates its API to address this edge case.

Step 3: Select a shipping option (optional)

By default, Rye will use the cheapest shipping option when a cart is checked out. This is a reasonable default as it minimizes the cost to your shopper, but sometimes the shopper would prefer to use a more expensive shipping option in order to get their products sooner.
The offer for the Amazon products we've been working with only have one available shipping option, but this isn't always the case. Shopify stores in particular quite often have a range of shipping options available with varying costs and delivery timeframes.
The updateCartSelectedShippingOptions mutation can be used to explicitly select your shopper's preferred shipping method.
mutation SelectShippingOption {
  updateCartSelectedShippingOptions(
    input: {
      # NOTE: Replace all of these values with ones from your cart!
      id: "TgDZ0GvuqZkVlmdhm94f"
      shippingOptions: [{
        store: "amazon"
        shippingId: "0-Default shipping method"
      }]
    }
  ) {
    cart {
      id
    }
    errors {
      code
      message
    }
  }
}
Of course, like any other cart API operation we can query any field we'd like from the Cart object here; we are not only limited to the id field. Note that the shippingOptions input is a list of shipping options; this is to support passing shipping options for multiple stores in a single API call. The store field inside a shippingOptions entry must align with the store value on the corresponding AmazonStore or ShopifyStore objects.

Address validation

Rye has fairly stringent address validation rules in place to reduce order failure rate. While no fields on the BuyerIdentityInput type are explicitly marked as being required, it is a good idea to provide as many fields as you can as we do run additional validation on these fields beyond what our schema advertises.
The exact set of validation rules applied depends on a variety of factors, but the destination country is the main one. For instance, provinceCode is a required field when shipping to the USA but can be safely omitted when shipping to an address in the UK. In general, our address validation logic is aligned with local expectations around the formatting of addresses.
There are a few other things to keep in mind here when passing addresses to Rye:
  • In the case of Shopify orders, the email you provide here will receive order update emails from Shopify. This can be inconvenient in cases where you are applying a mark up.
    • You may want to provide one of your own email addresses here, and then send your own communications out to shoppers by responding to our webhooks.
  • The phone value, if provided, must be a valid phone number in E.164 format.
  • The provinceCode value should generally be a valid ISO 3166-2 code without the country code prefix. For instance, AUK would represent the "Auckland" region of New Zealand. Providing the official code for the region is the most accurate method for specifying the delivery zone.
    • In cases where you do not know what code to use you can also provide the full region name (e.g. Auckland) and our API will attempt to match that name to the correct code automatically.
    • Only English province names are supported.
  • The lastName field is required, as some marketplaces we support ordering from also require this field. In some parts of the world, people do not have last names which can cause problems. Our recommendation in this case is to set lastName to the name of your company to work around this marketplace limitation.
    • Example: firstName: "John", lastName: "Rye".

Congratulations!

You've created a cart, attached a buyer identity, and selected a shipping option. You are now ready to place an order with the Rye API.
Otherwise, the next page in this section will walk you through dealing with abandoned carts.
Rye
Powered byHolocron