Cart & Checkout

Beta disclaimer
Please note that you are accessing the Beta version of Outshifter's APIs which are in the process of being tested before their official release. 
This being so, Outshifter does not give any warranties, whether express or implied, as to the suitability or usability of the APIs, its services, or any of its content. 
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.
Our order creation flow is as follows:
Cart: an object with all the items added to the cart by a potential buyer. The frontend can interact with our API to add, update or remove items.
Checkout Initiation: once the final customer is ready to initiate the order, an object with the cart data is needed for the checkout process. You can still update the cart at this time. 
Shipping Methods: the way orders will be sent. E.g. postal service, click & collect.
Payment Method: a payment provider. E.g., Stripe, Klarna.
Payment: this object contains status and additional data about payment. Payments are processed by third parties.
Checkout Completion: once the payment succeeds, the checkout is finished. 
Order Creation: When all the above is completed, the order will be released internally in Outshifter. OBS: the order id is created just before the payment is attempted and marked as pending.
Cart
Create a cart
Store on our database the items added to the cart by a potential buyer.
You can initiate the cart even before adding products to it, so you decide when it's more convenient for you to do it. You need to provide us though with the reference to the customer's session id that is created by you in the frontend.
post
https://api.outshifter.com/api
/cart
Create a cart
Body example:
{
   "customer_session_id": "92sdj34234",
   "currency": "EUR"
}
Response example:
{
    "cart_id": "dd961398-e3de-4204-9404-450b6170ddf3",
    "customer_session_id": "92sdj37257",
    "created_at": "2022-10-07T10:17:31.675Z",
    "updated_at": "2022-10-07T10:17:31.675Z",
    "line_items": [],
    "total_amount": 0,
    "currency": "EUR"
}
You may want to interact with the cart in the following ways:
add an additional item o multiple items to the cart object
update the quantity of an added item
remove an item or multiple items from the cart object
Add an item
post
https://api.outshifter.com/api
/cart/:id/item/add
Add an item to the cart
Body example:
{
   "line_items": [
      {
         "product_id": 112232,
         "variant_id": 231,
         "quantity": 2,
         "price_data": {
            "unit_price": "323.13",
            "tax": "12",
            "currency": "EUR"
         }
      }
   ]
}
Response example:
{
    "line_items": [
        {
            "id": "c383e935-38d6-4cee-8c50-30506e3476c3",
            "product_id": 0,
            "product_title": "",
            "product_image": [],
            "variant_id": null,
            "quantity": 1,
            "price_data": {
                "unit_price": 200,
                "tax": 12,
                "currency": "NOK"
            }
        }
    ]
}
It is possible to add more than one item on this endpoint.
Update an item
patch
https://api.outshifter.com/api
/cart/:id/item/update/:itemId
Update a cart item
Body example:
{
    "qty": 2
}
Response example:
{
    "message": "The item was updated successfully"
}
Remove an item
patch
https://api.outshifter.com/api
/cart/:id/item/delete/:itemId
Delete a cart item
Response example:
{
    "message": "The item was removed successfully"
}
Get cart information
At any time you can retrieve cart information with all the added items.
get
https://api.outshifter.com/api
/cart/:id
Get cart information by id
Below you can see a cart object response example with line items already added:
{
   "cart_id": 112321203,
   "customer_session_id": "92sdj34234",
   "created_at": "2022-04-05T13:20:16-04:00",
   "updated_at": "2022-04-05T13:20:16-04:00",
   "line_items":[
      {
         "product_id": 112232,
         "variant_id": 231,
         "quantity": 2,
         "price_data":{
            "unit_price": "323.13",
            "tax": "12",
            "currency": "EUR"
         }
      },
      {
         "product_id": 112000,
         "variant_id": null,
         "quantity": 1,
         "price_data":{
            "unit_price": "100.00",
            "tax": "12",
            "currency": "EUR"
         }
      }
   ],
   "total_amount": "1200.20",
   "currency":"EUR"
}
Delete cart by id
In case you need to delete a cart, it is possible via this endpoint.
delete
https://api.outshifter.com/api
/cart/:id
Delete a cart by id
Response example:
{
    "message": "The cart was deleted successfully"
}
Init payment with Klarna
post
https://api.outshifter.com/api
/cart/:id/init-payment-klarna
Checkout
Initiate the checkout
Once the customer proceeds to checkout in your front-end, you can create the checkout in our backend just with the cart data.
post
https://api.outshifter.com/api
/checkout
Create a checkout
Body example:
{
    "cart_id": "aasd3432rfsd"
}
Response example:
{
    "cart": {
        "createdAt": "2022-10-07T10:17:31.675Z",
        "updatedAt": "2022-10-07T11:15:56.000Z",
        "id": "dd961398-e3de-4204-9404-450b6170ddf3",
        "customer_session_id": "92sdj37257",
        "currency": "NOK",
        "total_amount": "200.00",
        "deletedAt": null,
        "line_items": [
            {
                "createdAt": "2022-10-07T10:35:15.189Z",
                "updatedAt": "2022-10-07T10:35:15.189Z",
                "id": "c383e935-38d6-4cee-8c50-30506e3476c3",
                "deletedAt": null,
                "variantId": null,
                "quantity": 1,
                "priceData": {
                    "id": "004b5ec6-edb8-4004-8d34-9e7769a91b46",
                    "unitPrice": "200.00",
                    "tax": "12.00",
                    "currency": "NOK"
                }
            }
        ]
    },
    "status": "ACTIVE",
    "total_price": "200.00",
    "total_tax": "12.00",
    "total_line_items_price": 200,
    "deletedAt": null,
    "success_url": null,
    "cancel_url": null,
    "payment_method": null,
    "email": null,
    "checkout_url": null,
    "createdAt": "2022-10-07T11:44:53.666Z",
    "updatedAt": "2022-10-07T11:44:53.666Z",
    "id": "67954a7d-7bb4-49ef-82a6-bbe491d949a6",
    "availablePaymentMethods": []
}
Checkout completion required data
You will not be able to proceed with payment without the following information:
personal information (name, email)
shipping information
billing information
payment method
shipping rate
Payment Methods
get
https://api.outshifter.com/api
/checkout/payment-methods
Get available payment methods for your seller id
Shipping rates
Each product in Outshifter has associated shipping options. With this endpoint, you can get the total shipping cost on your front-end just by providing the selected product ids. 
post
https://api.outshifter.com/api
/shipping/flat-rate
Shipping rates by product ids
An example body with two items:
{
    "items": [
	{
	    "productId": 920,
	    "quantity": 1
	},
	{
	    "productId": 4018,
	    "quantity": 1
	}
    ],
    "destination": {
    	"country": "NO"
    },
    "currency": "NOK"
}
Response example:
{
    "service_name": "Flat rate price to NO",
    "description": "By Outshifter",
    "service_code": "920-FRP,4108-FRP",
    "total_price": 350.00,
    "currency": "NOK"
}
Interacting with the checkout
Update the checkout
At any time you can update the checkout object. Maybe a user initiated the checkout with some information and then came back later and updated it, or maybe you want to store the information the customer provides in steps.
This endpoint allows you to add information or to update information that was stored in the Checkout Object.
patch
https://api.outshifter.com/api
/checkout/:id
Get checkout information by id
A body example, just adding the user name and email:
{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Johnson",
      "email": "[email protected]"
    }
}
Response example:
{
    "createdAt": "2022-10-07T11:44:53.666Z",
    "updatedAt": "2022-10-07T11:52:56.000Z",
    "id": "67954a7d-7bb4-49ef-82a6-bbe491d949a6",
    "deletedAt": null,
    "success_url": null,
    "cancel_url": null,
    "payment_method": null,
    "email": null,
    "status": "ACTIVE",
    "checkout_url": null,
    "total_price": "200.00",
    "total_tax": "12.00",
    "total_line_items_price": 200,
    "cart": {
        "createdAt": "2022-10-07T10:17:31.675Z",
        "updatedAt": "2022-10-07T11:15:56.000Z",
        "id": "dd961398-e3de-4204-9404-450b6170ddf3",
        "customer_session_id": "92sdj37257",
        "currency": "NOK",
        "total_amount": "200.00",
        "deletedAt": null,
        "line_items": [
            {
                "createdAt": "2022-10-07T10:35:15.189Z",
                "updatedAt": "2022-10-07T10:35:15.189Z",
                "id": "c383e935-38d6-4cee-8c50-30506e3476c3",
                "deletedAt": null,
                "variantId": null,
                "quantity": 1,
                "product": null,
                "priceData": {
                    "id": "004b5ec6-edb8-4004-8d34-9e7769a91b46",
                    "unitPrice": "200.00",
                    "tax": "12.00",
                    "currency": "NOK"
                }
            }
        ]
    },
    "billing_address": null,
    "shipping_address": {
        "id": "12f13194-0501-47c3-ab67-1c980f5a8a4b",
        "first_name": "John",
        "last_name": "Johnson",
        "phone_code": null,
        "phone": null,
        "company": null,
        "address1": null,
        "address2": null,
        "city": null,
        "province": null,
        "province_code": null,
        "country": null,
        "country_code": null,
        "zip": null
    }
}
Get the checkout
Retrieve the checkout object with the completed information up to that point.
get
https://api.outshifter.com/api
/checkout/:id
Get checkout information by id
Response example:
{
    "createdAt": "2022-10-07T11:44:53.666Z",
    "updatedAt": "2022-10-07T11:52:56.000Z",
    "id": "67954a7d-7bb4-49ef-82a6-bbe491d949a6",
    "deletedAt": null,
    "success_url": null,
    "cancel_url": null,
    "payment_method": null,
    "email": null,
    "status": "ACTIVE",
    "checkout_url": null,
    "total_price": "200.00",
    "total_tax": "12.00",
    "total_line_items_price": 200,
    "cart": {
        "createdAt": "2022-10-07T10:17:31.675Z",
        "updatedAt": "2022-10-07T11:15:56.000Z",
        "id": "dd961398-e3de-4204-9404-450b6170ddf3",
        "customer_session_id": "92sdj37257",
        "currency": "NOK",
        "total_amount": "200.00",
        "deletedAt": null,
        "line_items": [
            {
                "createdAt": "2022-10-07T10:35:15.189Z",
                "updatedAt": "2022-10-07T10:35:15.189Z",
                "id": "c383e935-38d6-4cee-8c50-30506e3476c3",
                "deletedAt": null,
                "variantId": null,
                "quantity": 1,
                "product": null,
                "priceData": {
                    "id": "004b5ec6-edb8-4004-8d34-9e7769a91b46",
                    "unitPrice": "200.00",
                    "tax": "12.00",
                    "currency": "NOK"
                }
            }
        ]
    },
    "billing_address": null,
    "shipping_address": {
        "id": "12f13194-0501-47c3-ab67-1c980f5a8a4b",
        "first_name": "John",
        "last_name": "Johnson",
        "phone_code": null,
        "phone": null,
        "company": null,
        "address1": null,
        "address2": null,
        "city": null,
        "province": null,
        "province_code": null,
        "country": null,
        "country_code": null,
        "zip": null
    }
}
Initiate payment
Once the customer has selected the payment method and completed the required personal and shipping information, the next step is to proceed with the payment.
There are two optional return URLs parameters you can add:
"success_url": where to redirect the final customer after the payment is fulfilled on the checkout.
"cancel_url": where to redirect the final customer if the checkout is not completed or the go back button is pressed.
In case no return URLs are provided, Outshifter creates as default its own success and cancels URL where the final customer is redirected and shown the corresponding information.
patch
https://api.outshifter.com/api
/checkout/:id/payment
Initiate a checkout payment
Body example:
{
   "success_url": "https://yourdomain.com?success=true`,
   "cancel_url": "https://yourdomain.com?canceled=true`,   
    "payment_method": "Stripe",
    "email": "[email protected]",
    "first_name": "Outshifter",
    "last_name": "Test",
    "phone_code": "+47",
    "phone": 99999999,
    "address1": "Møllergata 6",
    "city": "Oslo",
    "province": "Oslo",
    "country": "Norway",
    "country_code": "NO",
    "zip" : 123
}
As a response, you get the checkout URL you can use to redirect and allow the final customer to complete the payment. An order id is also created with pending status.
{
    "checkout_url": "https://checkout.stripe.com/pay/cs_test_b1VMRSqjnNbLRfT58rDbfId4annlCVwHy8caxZJcquValgOVZIO8MZ2H99#fidkdWxOYHwnPyd1blpxYHZxWjA0SVNSbjRDa3N8bkBQRnFSQ3Y9c0sxYm1mRnRtUWlSPHV2QjB0djJ9VGpDdUx0TEt%2FRjFsQzQwRDdmRmY0XWhMVTBocTxLfGBycjddU39VNDFWN1VdXHBdNTVGQGJoc2o1QicpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPydocGlxbFpscWBoJyknYGtkZ2lgVWlkZmBtamlhYHd2Jz9xd3BgeCUl",
    "order_id": 3232
}
Retrieve payment information
Once the payment is completed, you can get just the payment information of the checkout.
get
https://api.outshifter.com/api
/checkout/:id/payment
Get payment information by checkout id
Response example:
{
   "success_url": "https://yourdomain.com?success=true`,
   "cancel_url": "https://yourdomain.com?canceled=true`,   
   "payment_method": "Stripe",
   "email": "[email protected]",
   "billing_address": {
      "first_name": "Will",
      "last_name": "Smith",
      "phone_code": "+47",
      "phone": "45966288",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
   },
   "shipping_address": {
      "first_name": "Will",
      "last_name": "Smith",
      "phone_code": "+47",
      "phone": "45966288",
      "company": null,
      "address1": "Chestnut Street 92",
      "address2": "",
      "city": "Louisville",
      "province": "Kentucky",
      "province_code": "KY",
      "country": "United States",
      "country_code": "US",
      "zip": "40202"
   },
   "cart": {
   "cart_id": 112321203,
   "customer_session_id": "92sdj34234",
   "created_at": "2022-04-05T13:20:16-04:00",
   "updated_at": "2022-04-05T13:20:16-04:00",
   "line_items":[
      {
         "product_id": 112232,
         "variant_id": 231,
         "quantity": 2,
         "price_data":{
            "unit_price": "323.13",
            "tax": "12",
            "currency": "EUR"
         }
      },
      {
         "product_id": 112000,
         "variant_id": null,
         "quantity": 1,
         "price_data":{
            "unit_price": "100.00",
            "tax": "12",
            "currency": "EUR"
         }
      }
   ],
   "total_amount": "1200.20",
   "currency":"EUR"
}
}
Delete a checkout
In order not to overflow the database, unfinished checkouts are deleted. Anonymous and unfinished checkouts are deleted after 60 days from the last modification.
You may also manually delete a checkout yourself:
delete
https://api.outshifter.com/api
/checkout/:id
Delete a checkout by id
Response example:
{
    "message": "Checkout 67954a7d-7bb4-49ef-82a6-bbe491d949a6 was deleted.",
    "executed": true
}
​
Last modified 4mo ago