Checkout to Quote

This tutorial provides step-by-step instructions to convert an open checkout to a quote order, and then process that quote to payment.

Step 1: Convert a checkout to a quote

The following operations should be run with the buyer's JWT authentication token.

Create the checkout session

In order to allow a buyer to request a quote from your storefront, you'll first have to create a checkout and add the checkout lines.

This is done with the checkoutCreate mutation. See Create a Checkout Session for more details.

Request
mutation {
  checkoutCreate(
    input: {
      lines: [
        { variantId: "UHJvZHVjdFZhcmlhbnQ6NjQ2", quantity: 2 }
        { variantId: "UHJvZHVjdFZhcmlhbnQ6NTU5", quantity: 1 }
      ]
    }
  ) {
    created
    checkout {
      id
      token
      email
    }
    checkoutErrors {
      field
      message
      code
    }
  }
}
Show more ↓

Convert the checkout to a quote order

In order to convert this checkout to a quote order, use the checkoutConvertToNauticalQuoteOrder mutation with the checkout id.

Request
mutation {
  checkoutConvertToNauticalQuoteOrder(
    checkoutId: "Q2hlY2tvdXQ6OTIwZGQ5MjEtODljYy00YjA2LWI4NTYtMjFmM2M3YTNjMDZj"
  ) {
    order {
      id
      number
      userEmail
      status
      subStatus
      isPaid
      total {
        net {
          currency
          baseAmount
        }
      }
    }
    checkoutErrors {
      field
      message
      code
    }
  }
}
Show more ↓

Result

We now have a Nautical quote order.

note

For the following set of mutations, they will be done by the marketplace operator and you will therefore have to generate a JWT for the marketplace operator for subsequent mutations. That being said, keep your customer token for the final set of mutations in this walkthrough.

Step 2: Prepare the quote

After a buyer initiates a quote, the marketplace operator can prepare the quote by defining shipping and optionally customizing order line prices.

The following set of mutations must be run with an authentication token granted the manage_marketplace permission.

(Optional)Query suborders and available shipping methods

(Optional)Customize order line prices

Assign shipping methods and prices

You must select a shipping method for each seller within the order. You can optionally override shipping rates while defining shipping methods.

Argument	Usage
`order`	The `id` of the `nauticalOrder` for the active quote.
`input.seller`	The primary key (`pk`) of the seller you wish to target to assign the shipping method.
`input.shippingMethod`	The `id` of the shipping method you wish to assign to the seller order.
`input.newPrice`	(Optional) Enter a custom shipping price to override the configured shipping method price.

Repeat the nauticalOrderUpdateShipping mutation for each seller suborder within the order.

Request
mutation {
  nauticalOrderUpdateShipping(
    order: "TmF1dGljYWxPcmRlcjo0Ng=="
    input: {
      seller: "11"
      shippingMethod: "U2hpcHBpbmdNZXRob2Q6MTQ="
      newPrice: "20.00"
    }
  ) {
    order {
      subOrders {
        shippingMethod {
          name
        }
        shippingPrice {
          net {
            currency
            baseAmount
          }
        }
      }
    }
    orderErrors {
      field
      message
      code
    }
  }
}
Show more ↓

Step 3: Send quote to buyer

Once the quote has been prepared, it's time to send it to the buyer for payment.

Send quote to buyer

Use the nauticalQuoteOrderSendToCustomer mutation to send an email to the buyer with a link to view the prepared quote and submit payment. This mutation requires the following input:

Argument	Usage
`id`	The `id` of the quote order.
`storefrontUrl`	Your storefront URL path where the buyer can view the quote, in the format `https://{yourdomain}/quote`

Request
mutation {
  nauticalQuoteOrderSendToCustomer(
    id: "TmF1dGljYWxPcmRlcjo0Ng=="
    storefrontUrl: "https://ssm.fly.dev/quote"
  ) {
    orderErrors {
      field
      message
      code
    }
  }
}

(Optional)Cancel the order

Step 4: Process payment and finalize the order

If the customer accepts the quote, they can go ahead and submit payment to finalize the order.

Add billing address

This step is only required if the buyer didn't assign a billing address when creating the checkout.

Request
mutation {
  nauticalDraftOrderUpdate(
    id: "TmF1dGljYWxPcmRlcjo0Ng=="
    input: {
      billingAddress: {
        firstName: "Martha"
        lastName: "Mack"
        streetAddress1: "227 Green Motorway"
        city: "South Robert"
        postalCode: "85357"
        countryArea: "AZ"
        country: US
      }
    }
  ) {
    nauticalOrder {
      id
      token
      billingAddress {
        firstName
        lastName
        phone
        streetAddress1
        streetAddress2
        city
        postalCode
        countryArea
        country {
          country
          code
        }
      }
    }
    orderErrors {
      field
      message
      code
    }
  }
}
Show more ↓

(Optional)Query order total

Choose payment method

How you process a payment depends on the selected payment gateway.

Assuming you are using an integrated app like Stripe or Braintree, you will first need to generate a payment intent client secret that you will use for the next step.

With Stripe for example, the payment intent is created when the customer gets to the Stripe checkout screen. See Accepting Payments with Stripe for more information.

Request
query {
  getClientSecret(
    gateway: "nautical.payments.stripe"
    paymentInformation: {
      checkoutId: "Q2hlY2tvdXQ6NWEyZDQ5NTUtY2UwNS00YTZjLTkyNzEtNjdmMjY0ZWNlNDFl"
      paymentMethodToken: "pm_1OUGADCp3bxKlBq1ycTryyF6"
      customerEmail: "buyer@example.com"
      customerId: "cus_PIruOzl2CNfhsq"
      amount: 729.99
      currency: "USD"
    }
  )

Create a payment

Using the payment token from the chosen payment gateway, create a payment against the order:

Request
mutation {
  nauticalOrderPaymentCreate(
    orderId: "TmF1dGljYWxPcmRlcjo0Ng=="
    input: {
      gateway: "nautical.payments.stripe"
      token: "pi_3OUCwjCp3bxKlBq10DhR4aVU"
    }
  ) {
    order {
      token
      isPaid
      total {
        net {
          currency
          baseAmount
        }
      }
    }
    payment {
      id
      gateway
      total {
        currency
        baseAmount
      }
    }
    paymentErrors {
      field
      message
      code
    }
  }
}
Show more ↓

Finalize the order

Now that we have paid for the quote order, we can finally complete the order with the nauticalDraftOrderComplete mutation. This step converts the quote to a finalized nauticalOrder.

Request
mutation {
  nauticalDraftOrderComplete(
    paymentData: "{"amount":729.99}"
    token: "0d576241-075f-4fce-845c-ca693193b5d3"
  ) {
    order {
      isPaid
      id
    }
    orderErrors {
      field
      message
      code
    }
  }
}