Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

Purpose:

The purpose of this walkthrough is to show you how to create a new cart using the API.

 

Pre Requisites:

  • Shop module must be enabled (specifically that checkout page) to fetch the URL for redirecting to the secure cart page.

  • Offers or Products with the source shop enabled.

If source shop is not enabled on the items, the checkout won’t load the item.

API Endpoint

You need to make a POST request method to api/carts using your default instance domain.

For example: https://webforce.webforcehq.test/api/carts

9c091275-ca03-4393-909d-f3cfebf790ea.png

Open settings option menu / Click on Domains / Copy the default Domain

Structure for Cart payload

A valid payload would look like this:

Captura.JPG

Text for easy copy:

{
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com"
},
"source": "my_external_shop1_page",
"items": [
{
"id": "0845ac60-d17f-4870-ba4d-5819cec05a64",
"type": "product",
"quantity": 2
},
{
"id": "b523ae01-2128-4637-bcf0-d7570e2c778c",
"type": "offer",
"quantity": 1
},
{
"id": "f14ad2f4-31b9-453c-b1d2-4f3a5373c1d4",
"type": "product",
"variation_id": "1fe52282-0d89-4bd2-86ef-8d2a99509702",
"plan_id": "b9318036-2f54-41df-8d74-bd55a46c70bf",
"quantity": 1
}
]
}

 

If the contact key is set, the API creates a new lead using the specified information.

Captura1.JPG

Text for easy copy:

contact: not required
first_name: required | string max 255
last_name: not required | string max 255
email: required | valid email | string max 255

 

Used to specify where the cart comes from.

Captura2.JPG

Text for easy copy:

source: required | string max 255

Let's call each object set in the key items an item. An item should be created only if its information is valid; otherwise, the API returns data with a key named errors, where the errors are specified.

Captura3.JPG

Text for easy copy:

items: required | array | min 1 object

Structure for a Cart Item

Some fields are required in specific cases.

mceclip2.png

Text for easy copy:

id: valid id | string max 255
type: required | offer or product
plan_id: valid id | string max 255
quantity: required | numeric | min 1
variation_id: valid id | string max 255

Required fields

mceclip3.png

*Required 

mceclip4.png

Where can we find the ids that we need to send in the payload?

ID for a Product.

6d8e52d0-abf9-4c15-b330-68783d417df2.png

Go to products list / Select the product you require and Edit / Click on ID Button

ID for a Product Variation.

d3ad04e9-f44d-45b3-9b95-5e0bdf3c40e5.png

Open Edit product drawer / Click on Variations option menu / Select the variation you require and View details / Click on ID Button

ID for a Product Plan.

032172f9-f4e1-435e-bad0-e96a4d9bff0b.png

Open Edit product drawer / Click on Subscription plans option menu / Select the plan you require and View details / Click on ID Button

ID for an Offer.

dedaeaec-1b14-497b-b55d-65ee74f29203.png

Go to offers list / Select the offer you require and Edit / Click on ID Button

API Response

Structure for a Api response:

mceclip5.png

Text for easy copy:

id: the id related to the created cart
redirect_url: the url related to the cart

A recently created cart with errors would look like this:

mceclip6.png

Text for easy copy:

{

"data": {

"id": "45a5413b-52c1-4c1b-886b-7325eb92eea5",

"redirect_url": "example-domain.com/myshop/mycheckout?cart_id=45a5413b-52c1-4c1b-886b-7325eb92eea5",

"errors": {

"cart_item_2": {

"id": [

"The id field is required."

]

},

"cart_item_3": {

"variation_id": [

"The variation id field is required."

]

}

}

},

"message": "Cart created"

}

When we create a cart and each items are valid, the API doesn't return any errors key.

mceclip7.png

Text for easy copy:

{
"data": {
"id": "9421ac85-c6df-4277-800b-c9df997c16b0",
"redirect_url": "webforce.test/myshop/mycheckout?cart_id=9421ac85-c6df-4277-800b-c9df997c16b0"
},
"message": "Cart created"
}

if we visit it the URL the shop checkout loads the valid items related to the cart and prepare everything so that they can be paid.

Checkout Page

ec1cf085-0eb4-46fa-bed0-0cf9ccb33872.png

Note: the cart and its items will be managed using the business rules of the shop.

Checklist:

  • Active shop and products 

  • Offers

  • Active domain 

 

  • No labels