Skip to main content

Checkout API Guide

Creating a Checkout Session​

A Checkout object can be created for logged-in users and for anonymous (guest) users.

To create a Checkout object, use the checkoutCreate mutation.

  • If the call is made by an authenticated user, the created checkout will be assigned to that user.

  • If the call is not made by an authenticated user, the created checkout will not have a user assigned. A user email is not required at this stage, but it must be provided before adding a promo code, creating a payment, or completing the checkout.

Checkout.channel.countries provides a list of countries to which shipping is available, derived from all shipping methods assigned to the checkout's channel. This can be useful for rendering a country picker in the checkout view.

mutation CheckoutCreate($input: CheckoutCreateInput!) {
  checkoutCreate(input: $input) {
    checkout {
      id
      totalPrice {
        gross {
          amount
          currency
        }
      }
      isShippingRequired
      shippingMethods {
        id
        name
        active
        message
      }
      availableCollectionPoints {
        id
        name
        clickAndCollectOption
      }
      availablePaymentGateways {
        id
        name
        config {
          field
          value
        }
      }
    }
    errors {
      field
      code
    }
  }
}

Set Email​

When an anonymous checkout has been created without an email, the email must be set using CheckoutEmailUpdate before creating payment and completing the checkout.

mutation CheckoutEmailUpdate($id: ID, $email: String!) {
  checkoutEmailUpdate(id: $id, email: $email) {
    checkout {
      id
      email
    }
    errors {
      field
      message
    }
  }
}

Managing Lines​

To add an item to the cart, use checkoutLinesAdd. The total price will be updated automatically.

See also checkoutLinesDelete and checkoutLinesUpdate.

If the quantity is changed to 0, it will be removed from the checkout.

mutation CheckoutLinesAdd($id: ID, $lines: [CheckoutLineInput!]!) {
  checkoutLinesAdd(id: $id, lines: $lines) {
    checkout {
      lines {
        id
        variant {
          name
        }
        quantity
      }
      totalPrice {
        gross {
          currency
          amount
        }
      }
    }
  }
}

Creating Two Lines Using a Single Variant​

By default, if a single variant is added multiple times, the quantity of the variant is increased without adding a new line. To add the same variant as a separate line, use the forceNewLine flag.

When forceNewLine is not used and the variant exists in multiple lines, Saleor will create a new line with the provided quantity.

mutation CheckoutLinesAdd($id: ID, $lines: [CheckoutLineInput!]!) {
  checkoutLinesAdd(id: $id, lines: $lines) {
    checkout {
      lines {
        id
        variant {
          name
        }
        quantity
      }
      totalPrice {
        gross {
          currency
          amount
        }
      }
    }
  }
}

Setting Custom Line Prices​

This feature is only available for apps with HANDLE_CHECKOUTS permission.

The variant price of any item in the checkout can be overridden. The provided price will be treated as the base price of the variant. Applying a voucher or sale in the checkout will be applied on top of the overridden price.

The custom price can be set with the price field in the CheckoutLineInput in the following mutations:

  • checkoutCreate,
  • checkoutLinesAdd – when adding a variant that already exists in the checkout, the corresponding line gets overridden – the quantity is incremented and the price is updated.
  • checkoutLinesUpdate – overrides the existing line with the price provided in the mutation.
mutation CheckoutLinesAdd($id: ID, $lines: [CheckoutLineInput!]!) {
  checkoutLinesAdd(id: $id, lines: $lines) {
    checkout {
      id
      lines {
        variant {
          id
        }
        quantity
        totalPrice {
          gross {
            amount
            currency
          }
          net {
            amount
            currency
          }
        }
      }
    }
    errors {
      field
      message
    }
  }
}

Update Shipping and Billing Address​

Use checkoutShippingAddressUpdate and checkoutBillingAddressUpdate mutations to set the destination address.

Keep in mind that address affects the availability of the products.

Read more about shipping and billing in checkout.

mutation checkoutShippingAddressUpdate($checkoutId: ID!, $shippingAddress: AddressInput!) {
  checkoutShippingAddressUpdate(
    id: $checkoutId
    shippingAddress: $shippingAddress
  ) {
    checkout {
      id
      shippingAddress {
        ...AddressFragment
      }
      billingAddress {
        ...AddressFragment
      }
    }
  }
}

fragment AddressFragment on Address {
  id
  city
  phone
  postalCode
  companyName
  cityArea
  streetAddress1
  streetAddress2
  countryArea
  country {
    country
    code
  }
  firstName
  lastName
}

Update Delivery Method​

Use checkoutDeliveryMethodUpdate to pass the delivery method returned by the checkout query.

The return type in checkout.deliveryMethod can be either Warehouse or ShippingMethod, so a union type must be used.

Learn more about delivery methods and how Saleor return shipping methods.

See the GraphQL documentation to learn more about unions.

mutation CheckoutDeliveryMethodUpdate($id: ID, $deliveryMethodId: ID) {
  checkoutDeliveryMethodUpdate(
    id: $id, deliveryMethodId: $deliveryMethodId) 
  {
    errors {
      message
      field
    }
    checkout {
      deliveryMethod {
        ... on Warehouse {
          id
          name
        }
        ... on ShippingMethod {
          id
          name
        }
      }
    }
    __typename
  }
}

Apply a Promo Code​

Use checkoutAddPromoCode to add a voucher code or gift card to a checkout.

For more details, see the vouchers and gift cards guides.

mutation CheckoutAddPromoCode($id: ID, $promoCode: String!) {
  checkoutAddPromoCode(id: $id, promoCode: $promoCode) {
    checkout {
      id
      discount {
        amount
        currency
      }
      totalPrice {
        gross {
          amount
          currency
        }
      }
      voucherCode
      giftCards{
        last4CodeChars
      }
    }
    errors {
      field
      code
      message
    }
  }
}

Attach Customer to Checkout​

Use checkoutCustomerAttach to assign a user to an anonymous checkout.

  • When called by a logged-in customer, provide the checkoutId.
  • When called by an App, provide checkoutId and customerId, require the IMPERSONATE_USER permission.
mutation CheckoutCustomerAttach($id: ID, $customerId: ID) {
  checkoutCustomerAttach(id: $id, customerId: $customerId) {
    checkout {
      id
      email
      user {
        id
        email
      }
    }
    errors {
      field
      code
      message
    }
  }
}

Detach Customer from Checkout​

Use checkoutCustomerDetach to remove the assigned user from a checkout.

mutation CheckoutCustomerDetach($id: ID) {
  checkoutCustomerDetach(id: $id) {
    checkout {
      id
      email
      user {
        id
      }
    }
    errors {
      field
      code
      message
    }
  }
}

Completing checkout​

Checkout can be completed if all requirements are satisfied.

When the checkout is fully paid, the CHECKOUT_FULLY_PAID webhook will be triggered.

mutation CheckoutComplete($id: ID) {
  checkoutComplete(id: $id) {
    order {
      id
      status
    }
    errors {
      field
      message
    }
  }
}