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 Authorization header with a valid auth token is provided, the created checkout will be assigned to the user who is authenticated by this token.

  • If no authentication token is provided, the checkout is created for an anonymous user, and an email address is used to identify such a Checkout object, linking it with the anonymous user. User email is not required at this stage but must be provided before adding a promo code, creating a payment or completing checkout.

mutation {
  checkoutCreate(
    input: {
      channel: "default-channel"
      email: "customer@example.com"
      lines: [{ quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjk3" }]
      shippingAddress: {
        firstName: "John"
        lastName: "Doe"
        streetAddress1: "1470  Pinewood Avenue"
        city: "Michigan"
        postalCode: "49855"
        country: US
        countryArea: "MI"
      }
      billingAddress: {
        firstName: "John"
        lastName: "Doe"
        streetAddress1: "1470  Pinewood Avenue"
        city: "Michigan"
        postalCode: "49855"
        country: US
        countryArea: "MI"
      }
    }
  ) {
    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
    }
  }
}
Expand ▼

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: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
    email: "test_customer@example.com"
  ) {
    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 wll be removed from checkout.

mutation {
  checkoutLinesAdd(
    id: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
    lines: [{ quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjc0" }]
  ) {
    checkout {
      lines {
        id
        variant {
          name
        }
        quantity
      }
      totalPrice {
        gross {
          currency
          amount
        }
      }
    }
  }
}
Expand ▼

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 provided quantity

mutation {
  checkoutLinesAdd(
    id: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
    lines: [
      { quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjc0", forceNewLine: true }
      { quantity: 2, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjc0" }
    ]
  ) {
    checkout {
      lines {
        id
        variant {
          name
        }
        quantity
      }
      totalPrice {
        gross {
          currency
          amount
        }
      }
    }
  }
}
Expand ▼

Setting Custom Line Prices​

This feature is only available for apps with HANDLE_CHECKOUTS permission.

The variant price of any item in checkout can be overridden. The provided price will be treated as the base price of the variant. If you apply a voucher or sale in checkout, it will be used 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: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
    lines: [
      { quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6MzA2", price: 16.22 }
    ]
  ) {
    checkout {
      id
      lines {
        variant {
          id
        }
        quantity
        totalPrice {
          gross {
            amount
            currency
          }
          net {
            amount
            currency
          }
        }
      }
    }
    errors {
      field
      message
    }
  }
}
Expand ▼