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 ▼