Shipping methods
Handling shipping is a crucial part of any e-commerce solution. This section will guide you through fetching available shipping methods, including pick-up points, and selecting a shipping method using the Afosto Storefront JavaScript Client. You'll learn how to perform these actions in a custom checkout process.
Fetch Available Shipping Methods
We can fetch the shipping methods using the cart. This ensures we only get methods that are applicable to the current cart and its information. This way, only the methods available for the selected shipping country will be returned. It also calculates any pricing rules for the shipping methods, adding or removing shipping fees.
Here is a GraphQL query example to fetch available shipping methods, including pick-up points based on a postal code and country code. Without a postal code and country code, the pickup points with throw an error that these are required.
```js
import { gql } from '@afosto/storefront';
const query = gql`
query getCart($id: String!, $country_code: String!, $postal_code: String!) {
cart(id: $id) {
options {
shipping {
methods {
id
name
description
instruction
carrier
is_pickup_point
pickup_points(
country_code: $country_code
postal_code: $postal_code
) {
id
name
distance
address {
country_code
administrative_area
locality
postal_code
address_line_1
address_line_2
thoroughfare
premise_number
premise_number_suffix
}
}
pricing {
fixed
percentage
}
}
}
}
}
}
`;
const variables = {
id: 'my_cart_token',
countryCode: 'NL',
postalCode: '9723JA',
};
const response = await client.query(query, variables);
## Select a shipping method
When the customer has made its decision, we can add the shipping method to the cart. This can be done using the example below.
import { gql } from '@afosto/graphql-client';
import CoreProjectionFields from '../CoreProjectionFieldsFragment';
const AddShippingMethodToCart = gql`
mutation AddShippingMethodToCart($shipping_method_payload: AddShippingMethodToCartInput!) {
addShippingMethodToCart(input: $shipping_method_payload) {
cart {
...CoreProjectionFields
id
delivery {
method {
id
name
}
}
}
}
}
`;
const variables = {
shipping_method_payload: {
cartId: 'my_cart_token',
methodId: 'selected_shipping_method_id',
},
};
const response = await client.query(AddShippingMethodToCart, variables);import { gql } from '@afosto/graphql-client';
const CoreProjectionFields = gql`
fragment CoreProjectionFields on Cart {
id
adjustments {
description
amount
is_discount
is_percentage
outcome {
amount
}
}
items {
ids
brand
mpn
gtin
sku
quantity
subtotal
total
image
label
details {
pricing {
amount
}
meta_data
}
vat {
rate
amount
}
}
currency
is_including_vat
is_vat_shifted
subtotal
total
total_excluding_vat
fees {
shipping {
description
total
vat {
rate
amount
}
}
payment {
description
total
vat {
rate
amount
}
}
}
vat {
rate
amount
}
}
`;
export default CoreProjectionFields;
This query also includes a fragment to get information for the projection. The CoreProjectionFields fragment includes all the information you need to show a cost summary. The summary keeps the customer informed about extra costs added by their choices. In the hosted checkout we include this fragment in every step so keep the summary up to date.
## Pickup points
Some carriers provide methods that are pickup points. With these methods, a customer can select a nearby pickup point to deliver their order to. In the first example, we fetch the pickup points for all methods that have them. Using that data, you can present the options to the customer in your checkout.
### Search pickup points by postal code
If you want to offer your customer the option to search for pick-up points based on a postal code, you can use the following query. Adding a search field in your checkout that uses this query will help the customer select the best pickup point for them.
import { gql } from '@afosto/graphql-client';
const getPickupPointsForCartQuery = gql`
query GetPickupPointsForCart($id: String!, $postal_code: String!, $country_code: String!) {
cart(id: $id) {
id
delivery {
method {
pickup_points(country_code: $country_code, postal_code: $postal_code) {
id
name
carrier
distance
address {
country_code
administrative_area
locality
postal_code
address_line_1
address_line_2
thoroughfare
premise_number
premise_number_suffix
}
}
}
}
}
}
`;
const variables = {
id: 'my_cart_token',
countryCode: 'NL',
postalCode: '9712HW', // Update this based on user input
};
const response = await client.query(getPickupPointsForCartQuery, variables);
### Selecting the pickup point
To select the pickup point for a method, we need to do a separate mutation. This needs to be done after selecting the shipping method.
import { gql } from '@afosto/graphql-client';
import CoreProjectionFields from '../CoreProjectionFieldsFragment';
const addPickupPointToCartMutation = gql`
${CoreProjectionFields}
mutation AddPickUpPointToCart($pickup_point_payload: AddPickUpPointToCartInput!) {
addPickUpPointToCart(input: $pickup_point_payload) {
cart {
...CoreProjectionFields
delivery {
method {
id
name
}
pickup_point {
id
name
}
}
}
}
}
`;
export default addPickupPointToCartMutation;import { gql } from '@afosto/graphql-client';
const CoreProjectionFields = gql`
fragment CoreProjectionFields on Cart {
id
adjustments {
description
amount
is_discount
is_percentage
outcome {
amount
}
}
items {
ids
brand
mpn
gtin
sku
quantity
subtotal
total
image
label
details {
pricing {
amount
}
meta_data
}
vat {
rate
amount
}
}
currency
is_including_vat
is_vat_shifted
subtotal
total
total_excluding_vat
fees {
shipping {
description
total
vat {
rate
amount
}
}
payment {
description
total
vat {
rate
amount
}
}
}
vat {
rate
amount
}
}
`;
export default CoreProjectionFields;
By following these steps, you'll be able to effectively manage shipping methods in your custom checkout process with the Afosto Storefront JavaScript Client. Next step is selecting a payment method.