Shipping and Billing

Shipping

This step is only used if purchased items require shipping (if they are physical products). The user must select a specific shipping method to create shipping for this checkout. To signify whether shipping is required, use the isShippingRequired field in the Checkout object.

Adding address data

Address can be assigned using the checkoutShippingAddressUpdate mutation:

mutation {
  checkoutShippingAddressUpdate(
    shippingAddress: {
      country: PL
      firstName: "John"
      lastName: "Smith"
      streetAddress1: "ul. Tęczowa 7"
      postalCode: "53-030"
      city: "Wroclaw"
    }
    id: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
  ) {
    checkout {
      shippingAddress {
        firstName
        lastName
        streetAddress1
        city
        postalCode
      }
    }
    errors {
      field
      message
      code
    }
  }
}

Expand ▼

Successful response:

{
  "data": {
    "checkoutShippingAddressUpdate": {
      "checkout": {
        "shippingAddress": {
          "firstName": "John",
          "lastName": "Smith",
          "streetAddress1": "ul. Tęczowa 7",
          "city": "WROCLAW",
          "postalCode": "53-030"
        }
      },
      "errors": []
    }
  }
}

More information about address validation can be found on the address validation page.

Default address

Customers with accounts can set up default addresses, which will be attached automatically during the checkout creation. More information on API reference page for accountSetDefaultAddress.

Listing available shipping methods

After choosing the shipping address, API can be queried for available delivery methods in the user area:

query {
  checkout(id: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw") {
    shippingMethods {
      id
      name
      active
      price {
        currency
        amount
      }
    }
    availableCollectionPoints {
      id
      name
      clickAndCollectOption
    }
  }
}

Response:

{
  "data": {
    "checkout": {
      "shippingMethods": [
        {
          "id": "U2hpcHBpbmdNZXRob2Q6MTY1Nw==",
          "name": "DHL",
          "price": {
            "currency": "USD",
            "amount": 10.0
          },
          "active": true,
          "message": ""
        },
        {
          "id": "U2hpcHBpbmdNZXRob2Q6MTM=",
          "name": "UPS",
          "price": {
            "currency": "USD",
            "amount": 8.0
          },
          "active": false,
          "message": "Not available."
        }
      ],
      "availableCollectionPoints": [
        {
          "id": "V2FyZWhvdXNlOjU0NjliNWQ3LThmOGUtNGVmOS1iMGQxLWNhYWZmYTg4MjI1OQ==",
          "name": "Local Store",
          "clickAndCollectOption": "LOCAL"
        },
        {
          "id": "V2FyZWhvdXNlOjU0NjliNWQ3LThmOGUtNGVmOS1iMGQxLWNhYWZmYTg4MjI1OA==",
          "name": "Company HQ",
          "clickAndCollectOption": "ALL"
        }
      ]
    }
  }
}

Expand ▼

Shipping methods can be internal (defined in the Saleor Dashboard) or external (coming from the 3-rd party). Collection points are warehouses that allow picking-up orders e.g. for click & collect flow.

Selecting the delivery method

Use the checkoutDeliveryMethodUpdate mutation to effectively pair the specific Checkout object with the specified delivery method selected by the user.

This operation requires the following input:

• id: the checkout ID (the id field of the Checkout object).
• deliveryMethodId: the shipping method ID or Warehouse ID (from the shippingMethods or availableCollectionPoints field of the Checkout object).

In the following mutation, we assign a delivery method to the checkout using IDs from the previous example. Note that for the checkout object, we want to get back the update totalPrice including shipping costs:

Please note, that selecting collectionPoint or shippingMethod is mandatory for the checkout flow. In other words, setting deliveryMethod is mandatory.

mutation {
  checkoutDeliveryMethodUpdate(
    id: "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw"
    deliveryMethodId: "U2hpcHBpbmdNZXRob2Q6MTM="
  ) {
    checkout {
      id
      deliveryMethod {
        __typename
        ... on Warehouse {
          name
        }
        ... on ShippingMethod {
          name
        }
      }
      totalPrice {
        gross {
          amount
          currency
        }
      }
    }
    errors {
      field
      message
    }
  }
}

Expand ▼

As a result, we get an updated checkout object with a delivery method set:

{
  "data": {
    "checkoutDeliveryMethodUpdate": {
      "checkout": {
        "id": "Q2hlY2tvdXQ6ZTEzZDFjOTItOWJkNi00ODViLTgyMDctZTNhM2I5NjVkZTQw",
        "deliveryMethod": {
          __typename: "ShippingMethod"
          "name": "UPS"
        },
        "totalPrice": {
          "gross": {
            "amount": 25.99,
            "currency": "USD"
          }
        }
      },
      "errors": []
    }
  }
}

Expand ▼

Address Validation

The checkout's mutations that accept an address as an input have a field that can turn off the address validation. It allows assigning a partial or not fully valid address to the checkout. Providing country code is mandatory for all addresses regardless of the rules provided in this input.

The address validation input has two boolean fields:

• checkRequiredFields - signals Saleor to raise an error when the provided address doesn't have all the required fields. Set to true by default.
• checkFieldsFormat - signals Saleor to raise an error when the provided address doesn't match the expected format. Set to true by default.
• enableFieldsNormalization - determines if Saleor should apply normalization on address fields. Example: converting city field to uppercase letters. Set to true by default.

checkoutCreate

The checkoutCreate mutation has an optional input for providing shipping and billing addresses. If you want to provide only a part of the address, you can disable the address validation.

The mutation accepts validationRules as an input field.

mutation {
  checkoutCreate(
    input: {
      channel: "default-channel"
      email: "customer@example.com"
      lines: [{ quantity: 1, variantId: "UHJvZHVjdFZhcmlhbnQ6Mjk3" }]
      shippingAddress: { country: US }
      billingAddress: { postalCode: "XX-YYY", country: US }
      validationRules: {
        shippingAddress: { checkRequiredFields: false }
        billingAddress: { checkRequiredFields: false, checkFieldsFormat: false }
      }
    }
  ) {
    checkout {
      id
    }
    errors {
      field
      code
    }
  }
}

Expand ▼

The response contains the created checkout object:

{
  "data": {
    "checkoutCreate": {
      "checkout": {
        "id": "Q2hlY2tvdXQ6NGY1NjI1MDQtOWE2ZS00YjRjLWJiZWYtYmNjNDhkNWMwNDVj"
      },
      "errors": []
    }
  }
}

CheckoutShippingAddressUpdate

The checkoutShippingAddressUpdate mutation has an optional field for controlling the shipping address validation: validationRules.

mutation {
  checkoutShippingAddressUpdate(
    id: "Q2hlY2tvdXQ6MjU1MmYxYTctN2Q3MC00ODg5LTg1OWYtNGNiNWNlMGI4Zjhk"
    shippingAddress: { postalCode: "12-333", country: PL }
    validationRules: { checkRequiredFields: false }
  ) {
    errors {
      field
      message
      code
    }
    checkout {
      id
      shippingAddress {
        id
        postalCode
        firstName
        lastName
        country {
          code
        }
      }
    }
  }
}

Expand ▼

The response contains the updated checkout object:

{
  "data": {
    "checkoutShippingAddressUpdate": {
      "errors": [],
      "checkout": {
        "id": "Q2hlY2tvdXQ6MjU1MmYxYTctN2Q3MC00ODg5LTg1OWYtNGNiNWNlMGI4Zjhk",
        "shippingAddress": {
          "id": "QWRkcmVzczo4Mg==",
          "postalCode": "12-333",
          "firstName": "",
          "lastName": "",
          "country": {
            "code": "PL"
          }
        }
      }
    }
  }
}

Expand ▼

CheckoutBillingAddressUpdate

The checkoutBillingAddressUpdate mutation has an optional field for controlling the billing address validation: validationRules.

mutation {
  checkoutBillingAddressUpdate(
    id: "Q2hlY2tvdXQ6ZTM4NjMyYzItZTg5NS00ZjE4LTg3YTMtNjIwNGU0NzlmYjUw"
    validationRules: { checkFieldsFormat: false, checkRequiredFields: false }
    billingAddress: { country: GB, postalCode: "XX YYY" }
  ) {
    checkout {
      id
      billingAddress {
        streetAddress1
        city
        cityArea
        postalCode
        country {
          code
        }
        countryArea
      }
    }
  }
}

Expand ▼

The response contains the updated checkout object:

{
  "data": {
    "checkoutBillingAddressUpdate": {
      "checkout": {
        "id": "Q2hlY2tvdXQ6ZTM4NjMyYzItZTg5NS00ZjE4LTg3YTMtNjIwNGU0NzlmYjUw",
        "billingAddress": {
          "streetAddress1": "",
          "city": "",
          "cityArea": "",
          "postalCode": "XX YYY",
          "country": {
            "code": "GB"
          },
          "countryArea": ""
        }
      }
    }
  }
}

Expand ▼

note

The information about address validation can be found on the address validation page.

note

The shipping and billing addresses need to be valid when finalizing checkout by calling checkoutComplete mutation.

note

The fields for shipping and billing addresses will be normalized (if needed) on completing the checkout by calling checkoutComplete mutation.