Create a Cart

POST

/store/carts

Carts

Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and
the products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region.

If a customer is logged in, make sure to pass its ID or email within the cart's details so that the cart is attached to the customer.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request POST '{{BASE_URL}}/store/carts' \
--header 'Content-Type: application/json' \
--data-raw '{
    "region_id": "string",
    "sales_channel_id": "string",
    "country_code": "string",
    "context": {
        "ip": "::1",
        "user_agent": "Chrome"
    },
    "items": [
        {
            "variant_id": "string",
            "quantity": 0
        }
    ]
}'

Response Example

200 - Example 1

Request

Body Params application/json

The details of the cart to be created.

region_id

string

optional

The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default.

sales_channel_id

string

optional

The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources. If you add a publishable API key in the header of this request, you don't specify a sales channel ID, and the publishable API key is associated with one sales channel, that sales channel will be attached to the cart. If no sales channel is passed and no publishable API key header is passed or the publishable API key isn't associated with any sales channel, the cart will not be associated with any sales channel.

country_code

string

optional

The two character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.

context

object

optional

An object to provide context to the Cart. The context field is automatically populated with ip and user_agent

Example:

{"ip":"::1","user_agent":"Chrome"}

items

array [object {2}]

optional

An array of product variants to generate line items from.

variant_id

string

required

The ID of the Product Variant.

quantity

integer

required

The quantity to add into the cart.

Examples

Responses

🟢200Successfully created a new Cart

application/json

Body

The cart's details.

cart

object (Cart)

required

A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.

string

required

The cart's ID

Example:

cart_01G8ZH853Y6TFXWPG5EYE81X63

string <email> | null

required

The email associated with the cart

billing_address_id

string | null

required

The billing address's ID

Example:

addr_01G8ZH853YPY9B94857DY91YGW

shipping_address_id

string | null

required

The shipping address's ID

Example:

addr_01G8ZH853YPY9B94857DY91YGW

region_id

string

required

The region's ID

Example:

reg_01G1G5V26T9H8Y0M4JNE3YGA4G

customer_id

string | null

required

The customer's ID

Example:

cus_01G2SG30J8C85S4A5CHM2S1NS2

customer

object | null

optional

The details of the customer the cart belongs to.

payment_session

object | null

required

The details of the selected payment session in the cart.

payment_id

string | null

required

The payment's ID if available

Example:

pay_01G8ZCC5W42ZNY842124G7P5R9

payment

object | null

optional

The details of the payment associated with the cart.

completed_at

string <date-time> | null

required

The date with timezone at which the cart was completed.

payment_authorized_at

string <date-time> | null

required

The date with timezone at which the payment was authorized.

sales_channel_id

string | null

optional

The sales channel ID the cart is associated with.

Example:

null

created_at

string <date-time>

required

The date with timezone at which the resource was created.

updated_at

string <date-time>

required

The date with timezone at which the resource was updated.

deleted_at

string <date-time> | null

required

The date with timezone at which the resource was deleted.

shipping_total

integer

optional

The total of shipping

Example:

1000

discount_total

integer

optional

The total of discount rounded

Example:

800

raw_discount_total

integer

optional

The total of discount

Example:

800

item_tax_total

integer

optional

The total of items with taxes

Example:

8000

shipping_tax_total

integer

optional

The total of shipping with taxes

Example:

1000

tax_total

integer

optional

The total of tax

Example:

refunded_total

integer

optional

The total amount refunded if the order associated with this cart is returned.

Example:

total

integer

optional

The total amount of the cart

Example:

8200

subtotal

integer

optional

The subtotal of the cart

Example:

8000

refundable_amount

integer

optional

The amount that can be refunded

Example:

8200

gift_card_total

integer

optional

The total of gift cards

Example:

gift_card_tax_total

integer

optional

The total of gift cards with taxes

Example:

payment_sessions

array [object]

optional

The details of all payment sessions created on the cart.

type

enum<string>

required

The cart's type.

Allowed values:

defaultswapdraft_orderpayment_linkclaim

Default:

default

idempotency_key

string | null

required

Randomly generated key used to continue the completion of a cart in case of failure.

context

object | null

required

The context of the cart which can include info like IP or user agent.

Example:

{"ip":"::1","user_agent":"PostmanRuntime/7.29.2"}

metadata

object | null

required

An optional key-value map with additional details

Example:

{"car":"white"}

billing_address

object (Address)

optional

An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.

sales_channel

object (Sales Channel)

optional

A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.

shipping_address

object (Address)

optional

An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.

shipping_methods

array[object (Shipping Method) {20}]

optional

The details of the shipping methods added to the cart.

region

object (Region)

optional

A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.

gift_cards

array[object (Gift Card) {15}]

optional

An array of details of all gift cards applied to the cart.

discounts

array[object (Discount) {18}]

optional

An array of details of all discounts applied to the cart.

items

array[object (Line Item) {42}]

optional

The line items added to the cart.

🟠400Client Error or Multiple Errors

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

Modified at 2023-11-27 13:05:07

Refresh a Payment Session

Complete a Cart