Skip to main content
POST
/
store
/
carts
JS SDK
import Medusa from "@medusajs/js-sdk"

let MEDUSA_BACKEND_URL = "http://localhost:9000"

if (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {
  MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
}

export const sdk = new Medusa({
  baseUrl: MEDUSA_BACKEND_URL,
  debug: process.env.NODE_ENV === "development",
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
})

sdk.store.cart.create({
  region_id: "reg_123"
})
.then(({ cart }) => {
  console.log(cart)
})
{
  "cart": {
    "id": "<string>",
    "region": {
      "id": "<string>",
      "name": "<string>",
      "currency_code": "usd",
      "automatic_taxes": true,
      "countries": [
        {
          "id": "<string>",
          "iso_2": "us",
          "iso_3": "usa",
          "num_code": 840,
          "name": "<string>",
          "display_name": "<string>"
        }
      ],
      "payment_providers": [
        {
          "id": "<string>",
          "is_enabled": true
        }
      ],
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "region_id": "<string>",
    "customer_id": "<string>",
    "sales_channel_id": "<string>",
    "email": "jsmith@example.com",
    "currency_code": "usd",
    "shipping_address": {
      "id": "<string>",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "billing_address": {
      "id": "<string>",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "items": [
      {
        "id": "<string>",
        "title": "<string>",
        "subtitle": "<string>",
        "thumbnail": "<string>",
        "quantity": 123,
        "product": {
          "categories": [
            {}
          ],
          "type": {
            "id": "<string>",
            "metadata": {},
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": "2023-11-07T05:31:56Z",
            "value": "<string>"
          },
          "length": 123,
          "title": "<string>",
          "status": "draft",
          "options": [
            {
              "id": "<string>",
              "title": "<string>",
              "product": {},
              "product_id": "<string>",
              "values": [
                {
                  "id": "<string>",
                  "value": "<string>",
                  "option": {},
                  "option_id": "<string>",
                  "metadata": {},
                  "created_at": "2023-11-07T05:31:56Z",
                  "updated_at": "2023-11-07T05:31:56Z",
                  "deleted_at": "2023-11-07T05:31:56Z"
                }
              ],
              "metadata": {},
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z",
              "deleted_at": "2023-11-07T05:31:56Z"
            }
          ],
          "description": "<string>",
          "id": "<string>",
          "metadata": {},
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "variants": [
            {
              "options": [
                {
                  "id": "<string>",
                  "value": "<string>",
                  "option": {},
                  "option_id": "<string>",
                  "metadata": {},
                  "created_at": "2023-11-07T05:31:56Z",
                  "updated_at": "2023-11-07T05:31:56Z",
                  "deleted_at": "2023-11-07T05:31:56Z"
                }
              ],
              "product": {},
              "length": 123,
              "title": "<string>",
              "metadata": {},
              "id": "<string>",
              "width": 123,
              "weight": 123,
              "height": 123,
              "origin_country": "<string>",
              "hs_code": "<string>",
              "mid_code": "<string>",
              "material": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z",
              "deleted_at": "2023-11-07T05:31:56Z",
              "product_id": "<string>",
              "sku": "<string>",
              "barcode": "<string>",
              "ean": "<string>",
              "upc": "<string>",
              "allow_backorder": true,
              "manage_inventory": true,
              "inventory_quantity": 123,
              "variant_rank": 123,
              "calculated_price": {
                "id": "<string>",
                "is_calculated_price_price_list": true,
                "is_calculated_price_tax_inclusive": true,
                "calculated_amount": 123,
                "calculated_amount_with_tax": 123,
                "calculated_amount_without_tax": 123,
                "is_original_price_price_list": true,
                "is_original_price_tax_inclusive": true,
                "original_amount": 123,
                "currency_code": "usd",
                "calculated_price": {},
                "original_price": {},
                "original_amount_with_tax": 123,
                "original_amount_without_tax": 123
              }
            }
          ],
          "handle": "<string>",
          "subtitle": "<string>",
          "is_giftcard": true,
          "thumbnail": "<string>",
          "width": 123,
          "weight": 123,
          "height": 123,
          "origin_country": "<string>",
          "hs_code": "<string>",
          "mid_code": "<string>",
          "material": "<string>",
          "collection": {
            "id": "<string>",
            "title": "<string>",
            "handle": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "deleted_at": "2023-11-07T05:31:56Z",
            "products": [
              {}
            ],
            "metadata": {}
          },
          "collection_id": "<string>",
          "type_id": "<string>",
          "tags": [
            {
              "id": "<string>",
              "value": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z",
              "deleted_at": "2023-11-07T05:31:56Z",
              "metadata": {}
            }
          ],
          "images": [
            {
              "id": "<string>",
              "url": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z",
              "deleted_at": "2023-11-07T05:31:56Z",
              "metadata": {},
              "rank": 123
            }
          ],
          "discountable": true,
          "external_id": "<string>",
          "deleted_at": "2023-11-07T05:31:56Z"
        },
        "product_id": "<string>",
        "product_title": "<string>",
        "product_description": "<string>",
        "product_subtitle": "<string>",
        "product_type": "<string>",
        "product_collection": "<string>",
        "product_handle": "<string>",
        "variant": {
          "options": [
            {
              "id": "<string>",
              "value": "<string>",
              "option": {},
              "option_id": "<string>",
              "metadata": {},
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z",
              "deleted_at": "2023-11-07T05:31:56Z"
            }
          ],
          "product": {},
          "length": 123,
          "title": "<string>",
          "metadata": {},
          "id": "<string>",
          "width": 123,
          "weight": 123,
          "height": 123,
          "origin_country": "<string>",
          "hs_code": "<string>",
          "mid_code": "<string>",
          "material": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "deleted_at": "2023-11-07T05:31:56Z",
          "product_id": "<string>",
          "sku": "<string>",
          "barcode": "<string>",
          "ean": "<string>",
          "upc": "<string>",
          "allow_backorder": true,
          "manage_inventory": true,
          "inventory_quantity": 123,
          "variant_rank": 123,
          "calculated_price": {
            "id": "<string>",
            "is_calculated_price_price_list": true,
            "is_calculated_price_tax_inclusive": true,
            "calculated_amount": 123,
            "calculated_amount_with_tax": 123,
            "calculated_amount_without_tax": 123,
            "is_original_price_price_list": true,
            "is_original_price_tax_inclusive": true,
            "original_amount": 123,
            "currency_code": "usd",
            "calculated_price": {},
            "original_price": {},
            "original_amount_with_tax": 123,
            "original_amount_without_tax": 123
          }
        },
        "variant_id": "<string>",
        "variant_sku": "<string>",
        "variant_barcode": "<string>",
        "variant_title": "<string>",
        "variant_option_values": {
          "Color": "Red"
        },
        "requires_shipping": true,
        "is_discountable": true,
        "is_tax_inclusive": true,
        "compare_at_unit_price": 123,
        "unit_price": 123,
        "tax_lines": [
          {
            "item": {},
            "item_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "code": "<string>",
            "rate": 123,
            "provider_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z"
          }
        ],
        "adjustments": [
          {
            "item": {},
            "item_id": "<string>",
            "id": "<string>",
            "code": "<string>",
            "amount": 123,
            "cart_id": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z"
          }
        ],
        "cart": {},
        "cart_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "deleted_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "item_total": 123,
        "item_subtotal": 123,
        "item_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123
      }
    ],
    "shipping_methods": [
      {
        "id": "<string>",
        "cart_id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "amount": 123,
        "is_tax_inclusive": true,
        "shipping_option_id": "<string>",
        "data": {},
        "metadata": {},
        "tax_lines": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "code": "<string>",
            "rate": 123,
            "provider_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z"
          }
        ],
        "adjustments": [
          {
            "shipping_method": {},
            "id": "<string>",
            "code": "<string>",
            "amount": 123,
            "cart_id": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z"
          }
        ],
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123
      }
    ],
    "payment_collection": {
      "id": "<string>",
      "currency_code": "<string>",
      "amount": 123,
      "authorized_amount": 123,
      "captured_amount": 123,
      "refunded_amount": 123,
      "completed_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "metadata": {},
      "status": "canceled",
      "payment_providers": [
        {
          "id": "<string>"
        }
      ],
      "payment_sessions": [
        {
          "id": "<string>",
          "amount": 123,
          "currency_code": "usd",
          "provider_id": "<string>",
          "data": {},
          "context": {
            "customer": {
              "id": "cus_123"
            }
          },
          "status": "authorized",
          "authorized_at": "2023-11-07T05:31:56Z",
          "payment_collection": {},
          "payment": {
            "id": "<string>",
            "amount": 123,
            "authorized_amount": 123,
            "currency_code": "<string>",
            "provider_id": "<string>",
            "data": {},
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "captured_at": "2023-11-07T05:31:56Z",
            "canceled_at": "2023-11-07T05:31:56Z",
            "captured_amount": 123,
            "refunded_amount": 123,
            "captures": [
              {
                "id": "<string>",
                "amount": 123,
                "created_at": "2023-11-07T05:31:56Z",
                "created_by": "<string>",
                "payment": {}
              }
            ],
            "refunds": [
              {
                "id": "<string>",
                "amount": 123,
                "refund_reason_id": "<string>",
                "note": "<string>",
                "created_at": "2023-11-07T05:31:56Z",
                "created_by": "<string>",
                "payment": {},
                "refund_reason": {
                  "id": "<any>",
                  "label": "<any>",
                  "description": "<any>",
                  "metadata": "<any>",
                  "created_at": "<any>",
                  "updated_at": "<any>"
                }
              }
            ],
            "payment_collection": {},
            "payment_session": {}
          }
        }
      ],
      "payments": [
        {
          "id": "<string>",
          "amount": 123,
          "authorized_amount": 123,
          "currency_code": "<string>",
          "provider_id": "<string>",
          "data": {},
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "captured_at": "2023-11-07T05:31:56Z",
          "canceled_at": "2023-11-07T05:31:56Z",
          "captured_amount": 123,
          "refunded_amount": 123,
          "captures": [
            {
              "id": "<string>",
              "amount": 123,
              "created_at": "2023-11-07T05:31:56Z",
              "created_by": "<string>",
              "payment": {}
            }
          ],
          "refunds": [
            {
              "id": "<string>",
              "amount": 123,
              "refund_reason_id": "<string>",
              "note": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "created_by": "<string>",
              "payment": {},
              "refund_reason": {
                "id": "<any>",
                "label": "<any>",
                "description": "<any>",
                "metadata": "<any>",
                "created_at": "<any>",
                "updated_at": "<any>"
              }
            }
          ],
          "payment_collection": {},
          "payment_session": {}
        }
      ]
    },
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "original_item_total": 123,
    "original_item_subtotal": 123,
    "original_item_tax_total": 123,
    "item_total": 123,
    "item_subtotal": 123,
    "item_tax_total": 123,
    "original_total": 123,
    "original_subtotal": 123,
    "original_tax_total": 123,
    "total": 123,
    "subtotal": 123,
    "tax_total": 123,
    "discount_total": 123,
    "discount_tax_total": 123,
    "gift_card_total": 123,
    "gift_card_tax_total": 123,
    "shipping_total": 123,
    "shipping_subtotal": 123,
    "shipping_tax_total": 123,
    "original_shipping_total": 123,
    "original_shipping_subtotal": 123,
    "original_shipping_tax_total": 123,
    "promotions": [
      {
        "id": "<string>",
        "code": "<string>",
        "is_automatic": true,
        "application_method": {
          "value": "<string>",
          "type": "fixed",
          "currency_code": "<string>"
        }
      }
    ]
  }
}

Headers

​
x-publishable-api-key
string
required

Publishable API Key created in the Medusa Admin.

Query Parameters

​
fields
string

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Body

application/json

The cart's details. The details of the cart to be created.

​
region_id
string

The ID of the cart's region. This affects the prices and currency of the cart.

​
shipping_address
object

The address's details.

​
billing_address
object

The address's details.

​
email
string<email>

The email of the cart's customer.

​
currency_code
string

The cart's currency code. If not provided, the region's currency is used. This affects prices in the cart, as well.

Example:

"usd"

​
items
object[]

The cart's items.

​
sales_channel_id
string

The ID of the sales channel that cart is created in. Only products available in that sales channel can be added to the cart. If not provided, the store's default sales channel is associated with the cart instead.

​
metadata
object

The cart's metadata, can hold custom key-value pairs.

​
additional_data
object

Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Response

OK

The cart's details.

​
cart
object
required

The cart's details.