GraphQL API
Search…
Checkout & Payments
Flow from adding an item to the cart to completing the order
The below process describes the key milestones in the checkout process flow in Outshifter. There are also additional steps that may occur along the way; however, the purpose of this instruction is to deliver a base reference for the user to work with. We assume that at this stage, you have already completed the steps included in the Getting Started section of this chapter and that you are familiar with the basic setup of the Outshifter GraphQL API.
Our order creation flow is as follows:
  • Cart: an object will all the items added to the cart by a potential buyer. This has to be handled on the frontend. Alternatively
  • Checkout Initiation: an object which groups all the data needed for the checkout process. You can still update at this time so it can be used as an alternative cart if wanted to.
  • Shipping Methods: the way orders will be sent. E.g. postal service, click & collect.
  • Payment Method: a payment provider. E.g., Stripe, Klarna.
  • Payments: this object contains status and additional data about payment. Payments are processed and stocks reserved.
  • Checkout Completion: once the payment succeeds, the checkout is finished.
  • Order Creation: When all the above is completed, the order will be created internally in Outshifter.

Cart

If you are not using Outshifter's storefront SDK, the shopping cart has to be handled by the partner's built frontend.
You may also use the checkout as a cart. If you check the "Updating the checkout items" section below, you can see how to manage the items in the checkout once initiated.

Checkout initiation

Checkout permissions

A Checkout initiation object can only be created for logged in partner users, who can then query the created checkout data.

Checkout creation

To create a Checkout object, use the checkoutCreate mutation.
This mutation takes the following input:
  • channel: Slug of a channel in which to create checkout.
  • email: the final customer's email address.
  • shippingAddress: the shipping address (if needed).
  • billingAddress: the billing address.
  • items: a list of checkout items (products), each item contains the product ID, a product variant ID and its quantity.
The resulting Checkout object contains the following fields:
  • id: a unique checkout ID.
  • totalPrice: the total price of the checkout items and shipping costs.
  • availableShippingMethods: a list of available shipping methods for this checkout. If the items in the cart require shipment.
  • availablePaymentGateways: a list of payment gateways that are currently configured on your partner Outshifter account and can be used to pay for the checkout. Only gateways which support the checkout currency are returned. For each gateway, API returns an ID, a name, and a config object, which for some gateways may return additional information required to process the payment in the frontend.
In case there was an error after the mutation was sent, you will receive an error object in the result.

Example

The mutation creates the checkout object and returns the checkout information.
Mutation -> CheckoutCreateMutation
Mutation input -> CheckoutCreateInput
Mutation response -> CheckoutCreate
1
mutation {
2
checkoutCreate(
3
input: {
4
channel: "partner-name",
6
items: [{
7
productId: 244,
8
variantName: "Small-Black"
9
quantity: 1,
10
}],
11
shippingAddress: {
12
firstName: "John"
13
lastName: "Doe"
14
address: "Nydalsveien 14"
15
city: "Oslo"
16
postalCode: "1484"
17
country: "Norway"
18
countryCode: "NO"
19
}
20
billingAddress: {
21
firstName: "John"
22
lastName: "Doe"
23
address: "Nydalsveien 14"
24
city: "Oslo"
25
postalCode: "1484"
26
country: US
27
countryArea: "MI"
28
}
29
}
30
) {
31
checkout {
32
id
33
totalPrice {
34
amount
35
currency
36
}
37
availableShippingMethods {
38
id
39
name
40
}
41
availablePaymentGateways {
42
id
43
name
44
}
45
}
46
errors {
47
field
48
code
49
}
50
}
Copied!
And in the response you get the requested information for the checkout:
1
{
2
"data": {
3
"checkoutCreate": {
4
"checkout": {
5
"id": "Q2hlY2tvdXQ6ZmE5ZjBkMjYtMWM3NC00MDgyLTk3MzktYTIxOGE2NzVjMDZk",
6
"totalPrice": {
7
"amount": 1000,
8
"currency": "USD"
9
},
10
"availableShippingMethods": [
11
{
12
"id": "2",
13
"name": "UPS"
14
},
15
{
16
"id": "4",
17
"name": "DHL"
18
}
19
],
20
"availablePaymentGateways": [
21
{
22
"id": "1",
23
"name": "Klarna",
24
},
25
{
26
"id": "2",
27
"name": "Stripe",
28
}
29
]
30
},
31
"errors": []
32
}
33
}
34
}
Copied!

Updating items

You may add, update or remove a product from the checkout. This allows you to treat the checkout as a shopping cart if you want to.

Adding a product

Mutation -> checkoutItemsAdd
Use the add item's mutation and you will receive back the updated checkout.
1
mutation {
2
checkoutItemsAdd(
3
id: "4b22fbc0-b095-4937-a08e-bd18d04c951a",
4
items: [{
5
quantity: 1,
6
productId: 243,
7
variantName: "Small-Red"
8
}]
9
) {
10
checkout {
11
items {
12
id
13
variant {
14
name
15
}
16
quantity
17
}
18
totalPrice {
19
currency
20
amount
21
}
22
}
23
}
24
}
Copied!
1
{
2
"data": {
3
"checkoutItemsAdd": {
4
"checkout": {
5
"items": [
6
{
7
"productId": "321"
8
"variant": {
9
"name": "Small-Black"
10
},
11
"quantity": 1
12
}
13
],
14
"totalPrice": {
15
"currency": "USD",
16
"amount": 1000
17
}
18
}
19
}
20
}
21
}
Copied!

Updating a product

Removing a product

Shipping

The user must select a specific shipping method to create shipping for the checkout.
You have simple options for shipments:
  • Get available shipping methods
  • Select a shipping method
  • Update the shipping address of a initiated checkout

Available shipping methods

Based on the shipping address provided, you can query the available shipping methods.
Outshifter has a standardised shipping solution that is dynamic depending on the provided shipping address.
  • Click & Collect - Outshifter Warehouse Oslo
The customer can pick up the package
  • Picking point
Based on the zip code, you will receive available picking points on the customer's area.
  • Home delivery - Standard
Deliver the products at the customer's home. Standard shipping may take between 1 to 3 days.
  • Home delivery - Express
Deliver the products at the customer's home. Express shipping should take 1 day.
1
query {
2
checkout(checkoutId: "853ca234-b113-4021-8434-b37087d652a1"){
3
availableShippingMethods {
4
id
5
name
6
delivery
7
price {
8
currency
9
amount
10
}
11
}
12
}
13
}
Copied!
Response:
1
{
2
"data": {
3
"checkout": {
4
"availableShippingMethods": [
5
{
6
"id": "U2hpcHBpbmdNZXRob2Q6MTY1Nw==",
7
"name": "Click & Collect - Outshifter Warehouse Oslo",
8
"delivery": "1 day"
9
"price": {
10
"currency": "USD",
11
"amount": "00.00"
12
}
13
},
14
{
15
"id": "U2hpcHBpbmdNZXRob2Q6MTY1Nw==",
16
"name": "Picking point - Rema 1000 Nydalen",
17
"delivery": "1 day",
18
"price": {
19
"currency": "USD",
20
"amount": "10.00"
21
}
22
},
23
{
24
"id": "U2hpcHBpbmdNZXRob2Q6MTM=",
25
"name": "Home Delivery - Standard",
26
"delivery": "1 to 3 days"
27
"price": {
28
"currency": "USD",
29
"amount": "15.00"
30
}
31
},
32
{
33
"id": "U2hpcHBpbmdNZXRob2Q6MTM=",
34
"name": "Home Delivery - Express",
35
"delivery": "1 day",
36
"price": {
37
"currency": "USD",
38
"amount": "20.00"
39
}
40
},
41
],
42
}
43
}
44
}
Copied!

Select a shipping method

You must provide a delivery method before submitting the checkout. If you have not provided it when creating the checkout, you can add it later.
1
mutation {
2
checkoutSetDeliveryMethod(
3
checkoutId: "fd18c322-f816-406b-a71f-d9ce6a39c768"
4
deliveryMethodId: "U2hpcHBpbmdNZXRob2Q6MTM="
5
) {
6
checkout {
7
id
8
deliveryMethod {
9
name
10
}
11
}
12
totalPrice {
13
amount
14
currency
15
}
16
}
17
errors {
18
field
19
message
20
}
21
}
22
}
Copied!
Response:
1
{
2
"data": {
3
"checkoutDeliveryMethodUpdate": {
4
"checkout": {
5
"id": "fd18c322-f816-406b-a71f-d9ce6a39c768",
6
"deliveryMethod": {
7
"name": "Home delivery - Express"
8
},
9
"totalPrice": {
10
"amount": "99.99",
11
"currency": "USD"
12
}
13
},
14
"errors": []
15
}
16
}
17
}
Copied!

Update shipping address

In case needed, shipping address can be updated using the checkoutShippingAddressUpdate mutation.
1
mutation {
2
checkoutShippingAddressUpdate(
3
checkoutId: "58f4ca17-9c6f-437b-8204-beb47bbee364"
4
shippingAddress: {
5
firstName: "John"
6
lastName: "Doe"
7
streetAddress1: "Nydalsveien 15"
8
postalCode: "0484"
9
city: "Oslo"
10
country: "NO"
11
}
12
) {
13
checkout {
14
shippingAddress {
15
firstName
16
lastName
17
address
18
city
19
postalCode
20
}
21
}
22
errors {
23
field
24
message
25
code
26
}
27
}
28
}
Copied!
Response:
1
{
2
"data": {
3
"checkoutShippingAddressUpdate": {
4
"checkout": {
5
"shippingAddress": {
6
"firstName": "John",
7
"lastName": "Doe",
8
"address1": "Nydalsveien 15",
9
"city": "Oslo",
10
"postalCode": "0184"
11
}
12
},
13
"errors": []
14
}
15
}
16
}
Copied!

Payment

Depending on the selected payment gateway, you will need to use the JavaScript form which will be then integrated to Outshifter.
  • Partner requests for available payment methods
  • Outshifer sends available payment methods
  • After the payment is successful, the partner sends this information to confirm the order creation
  • Outshifter returns an object with the created order

Available payment gateways

Available payment gateways can be listed from the Checkout.availablePaymentGateways field. Depending on the chosen gateway, you may need additional configuration.
1
query {
2
checkout(checkoutId: "853ca234-b113-4021-8434-b37087d652a1"){
3
availablePaymentGateways {
4
id
5
name
6
}
7
}
8
}
Copied!
Outshifter works with the following payment methods. You as a partner will need to implement them on the frontend. Follow instructions from their official documentation:
  • Klarna
Klarna Docs - Klarna Payments JavaScript SDK
  • Stripe
Stripe Elements

Checkout completion

After the payment is successful, you will be able to trigger the internal order creation.
Go to the next section to learn more about order creation:

Removing old checkouts

In order not to overflow the database, unfinished checkouts are deleted. Anonymous and unfinished checkouts are deleted after a specified period of time from the last modification:
  • created checkouts with items, after 30 days
  • checkouts without items, after 6 hours