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
Open settings option menu / Click on Domains / Copy the default Domain
Structure for Cart payload
A valid payload would look like this:
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.
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.
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.
Text for easy copy:
items: required | array | min 1 object
Structure for a Cart Item
Some fields are required in specific cases.
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
*Required
Where can we find the ids that we need to send in the payload?
ID for a Product.
Go to products list / Select the product you require and Edit / Click on ID Button
ID for a Product Variation.
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.
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.
Go to offers list / Select the offer you require and Edit / Click on ID Button
API Response
Structure for a Api response:
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:
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.
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
Note: the cart and its items will be managed using the business rules of the shop.
Checklist:
Active shop and products
Offers
Active domain