Medusa Storefront API (1.0.0)

License: MIT

API reference for Medusa's Storefront endpoints. All endpoints are prefixed with /store.

Authentication

To send requests as an authenticated customer, you must use the Cookie Session ID.

Cookie Session ID

Use a cookie session to send authenticated requests.

If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.

If you're sending requests using cURL, you must set the Session ID in the cookie manually.

To do that, send a request to authenticate the customer and pass the cURL option -v:

curl -v --location --request POST 'https://medusa-url.com/store/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "password": "supersecret"
}'

The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:

Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;

Copy the value after connect.sid (without the ; at the end) and pass it as a cookie in subsequent requests as the following:

curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \
--header 'Cookie: connect.sid={sid}'

Where {sid} is the value of connect.sid that you copied.

Security Scheme Type: API Key

Cookie parameter name: connect.sid

Expanding Fields

In many endpoints you'll find an expand query parameter that can be passed to the endpoint. You can use the expand query parameter to unpack an entity's relations and return them in the response.

Please note that the relations you pass to expand replace any relations that are expanded by default in the request.

Expanding One Relation

For example, when you retrieve a product, you can retrieve its collection by passing to the expand query parameter the value collection:

curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection"

Expanding Multiple Relations

You can expand more than one relation by separating the relations in the expand query parameter with a comma.

For example, to retrieve both the variants and the collection of a product, pass to the expand query parameter the value variants,collection:

curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection"

Prevent Expanding Relations

Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.

For example:

curl "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand"

This would retrieve the product with only its properties, without any relations like collection.

Selecting Fields

In many endpoints you'll find a fields query parameter that can be passed to the endpoint. You can use the fields query parameter to specify which fields in the entity should be returned in the response.

Please note that if you pass a fields query parameter, only the fields you pass in the value along with the id of the entity will be returned in the response.

Also, the fields query parameter does not affect the expanded relations. You'll have to use the expand parameter instead.

Selecting One Field

For example, when you retrieve a list of products, you can retrieve only the titles of the products by passing title as a value to the fields query parameter:

curl "http://localhost:9000/store/products?fields=title"

As mentioned above, the expanded relations such as variants will still be returned as they're not affected by the fields parameter.

You can ensure that only the title field is returned by passing an empty value to the expand query parameter. For example:

curl "http://localhost:9000/store/products?fields=title&expand"

Selecting Multiple Fields

You can pass more than one field by seperating the field names in the fields query parameter with a comma.

For example, to select the title and handle of a product:

curl "http://localhost:9000/store/products?fields=title,handle"

Retrieve Only the ID

You can pass an empty fields query parameter to return only the ID of an entity. For example:

curl "http://localhost:9000/store/products?fields"

You can also pair with an empty expand query parameter to ensure that the relations aren't retrieved as well. For example:

curl "http://localhost:9000/store/products?fields&expand"

Query Parameter Types

This section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.

Strings

You can pass a string value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?title=Shirt"

If the string has any characters other than letters and numbers, you must encode them.

For example, if the string has spaces, you can encode the space with + or %20:

curl "http://localhost:9000/store/products?title=Blue%20Shirt"

You can use tools like this one to learn how a value can be encoded.

Integers

You can pass an integer value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?offset=1"

Boolean

You can pass a boolean value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/store/products?is_giftcard=true"

Date and DateTime

You can pass a date value in the form <parameter_name>=<value>. The date must be in the format YYYY-MM-DD.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17"

You can also pass the time using the format YYYY-MM-DDTHH:MM:SSZ. Please note that the T and Z here are fixed.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z"

Array

Each array value must be passed as a separate query parameter in the form <parameter_name>[]=<value>. You can also specify the index of each parameter in the brackets <parameter_name>[0]=<value>.

For example:

curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"

Note that the -g parameter passed to curl disables errors being thrown for using the brackets. Read more here.

Object

Object parameters must be passed as separate query parameters in the form <parameter_name>[<key>]=<value>.

For example:

curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"

Pagination

Query Parameters

In listing endpoints, such as list customers or list products, you can control the pagination using the query parameters limit and offset.

limit is used to specify the maximum number of items that can be return in the response. offset is used to specify how many items to skip before returning the resulting entities.

You can use the offset query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.

For example, to limit the number of products returned in the List Products endpoint:

curl "http://localhost:9000/store/products?limit=5"

Response Fields

In the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: count, limit, and offset.

Similar to the query parameters, limit is the maximum number of items that can be returned in the response, and field is the number of items that were skipped before the entities in the result.

count is the total number of available items of this entity. It can be used to determine how many pages are there.

For example, if the count is 100 and the limit is 50, you can divide the count by the limit to get the number of pages: 100/50 = 2 pages.

Auth

Auth endpoints that allow authorization of customers and manages their sessions.

Customer Login

Logs a Customer in and authorizes them to view their details. Successful authentication will set a session cookie in the Customer's browser.

Request Body schema: application/json

email required	string The Customer's email.
password required	string The Customer's password.

Responses

Response Schema: application/json

object (Customer)

Represents a customer

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The customer's billing address ID
created_at required	string <date-time> The date with timezone at which the resource was created.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string <email> The customer's email
first_name required	string or null Example: "Arno" The customer's first name
has_account required	boolean Default: false Whether the customer has an account or not
id required	string Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
last_name required	string or null Example: "Willms" The customer's last name
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
phone required	string or null Example: 16128234334802 The customer's phone number
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	Array of objects (Address) Available if the relation `shipping_addresses` is expanded.
orders	Array of objects Available if the relation `orders` is expanded.
	Array of objects (Customer Group) The customer groups the customer belongs to. Available if the relation `groups` is expanded.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"email": "string",
"password": "string"
}

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Customer Log out

Destroys a Customer's authenticated session.

Authorizations:

Cookie Session ID

Responses

Request samples

cURL

curl --location --request DELETE 'https://medusa-url.com/store/auth' \
--header 'Cookie: connect.sid={sid}'

Response samples

Content type

application/json

Example

Not Allowed Error

{"message": "Discount must be set to dynamic",
"type": "not_allowed"
}

Get Current Customer

Gets the currently logged in Customer.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

object (Customer)

Represents a customer

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The customer's billing address ID
created_at required	string <date-time> The date with timezone at which the resource was created.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string <email> The customer's email
first_name required	string or null Example: "Arno" The customer's first name
has_account required	boolean Default: false Whether the customer has an account or not
id required	string Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
last_name required	string or null Example: "Willms" The customer's last name
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
phone required	string or null Example: 16128234334802 The customer's phone number
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	Array of objects (Address) Available if the relation `shipping_addresses` is expanded.
orders	Array of objects Available if the relation `orders` is expanded.
	Array of objects (Customer Group) The customer groups the customer belongs to. Available if the relation `groups` is expanded.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged
medusa.auth.getSession()
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

Content type

application/json

{"customer": {"id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"email": "user@example.com",
"first_name": "Arno",
"last_name": "Willms",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_addresses": [{"id": null,
"customer_id": null,
"customer": { },
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"country": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"phone": 16128234334802,
"has_account": false,
"orders": [{ }
],
"groups": [{"id": null,
"name": null,
"customers": [ ],
"price_lists": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Check if email exists

Checks if a Customer with the given email has signed up.

path Parameters

required

string <email>

The email to check if exists.

Responses

Response Schema: application/json

exists

boolean

Whether email exists or not.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.auth.exists('user@example.com')

Response samples

Content type

application/json

{"exists": true
}

Cart

Cart endpoints that allow handling carts in Medusa.

Add a Shipping Method

Adds a Shipping Method to the Cart.

path Parameters

required

string

The cart ID.

Request Body schema: application/json

option_id required	string ID of the shipping option to create the method from
data	object Used to hold any data that the shipping method may need to process the fulfillment of the order. Look at the documentation for your installed fulfillment providers to find out what to send.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

Payload
JS Client
cURL

Content type

application/json

{"option_id": "string",
"data": { }
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Calculate Cart Taxes

Calculates taxes for a cart. Depending on the cart's region this may involve making 3rd party API calls to a Tax Provider service.

path Parameters

required

string

The Cart ID.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

cURL

curl --location --request POST 'https://medusa-url.com/store/carts/{id}/taxes'

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Complete a Cart

Completes a cart. The following steps will be performed. Payment authorization is attempted and if more work is required, we simply return the cart for further updates. If payment is authorized and order is not yet created, we make sure to do so. The completion of a cart can be performed idempotently with a provided header Idempotency-Key. If not provided, we will generate one for the request.

path Parameters

required

string

The Cart id.

Responses

Response Schema: application/json

type	string Enum: "order" "cart" "swap" The type of the data property.
	Order (object) or Cart (object) or Swap (object) The data of the result object. Its type depends on the type field.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.complete(cart_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

Content type

application/json

{"type": "order",
"data": {"id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 2,
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"edits": [{ }
],
"gift_card_transactions": [{"id": null,
"gift_card_id": null,
"gift_card": { },
"order_id": null,
"order": { },
"amount": null,
"created_at": null,
"is_taxable": null,
"tax_rate": null
}
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"shipping_total": 1000,
"discount_total": 800,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"paid_total": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0,
"returnable_items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Create a Cart

Creates a Cart within the given region and with the initial items. If no region_id is provided the cart will be associated with the first Region available. If no items are provided the cart will be empty after creation. If a user is logged in the cart's customer id and email will be set.

Request Body schema: application/json

region_id	string The ID of the Region to create the Cart in.
sales_channel_id	string [EXPERIMENTAL] The ID of the Sales channel to create the Cart in.
country_code	string The 2 character ISO country code to create the Cart in. See a list of codes.
	Array of objects An optional array of `variant_id`, `quantity` pairs to generate Line Items from.
context	object Example: {"ip":"::1","user_agent":"Chrome"} An optional object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

Payload
JS Client
cURL

Content type

application/json

{"region_id": "string",
"sales_channel_id": "string",
"country_code": "string",
"items": [{"variant_id": "string",
"quantity": 0
}
],
"context": {"ip": "::1",
"user_agent": "Chrome"
}
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Create Payment Sessions

Creates Payment Sessions for each of the available Payment Providers in the Cart's Region.

path Parameters

required

string

The id of the Cart.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.createPaymentSessions(cart_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Remove Discount

Removes a Discount from a Cart.

path Parameters

id required	string The id of the Cart.
code required	string The unique Discount code.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.deleteDiscount(cart_id, code)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Delete a Line Item

Removes a Line Item from a Cart.

path Parameters

id required	string The id of the Cart.
line_id required	string The id of the Line Item.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.lineItems.delete(cart_id, line_id)
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Update a Line Item

Updates a Line Item if the desired quantity can be fulfilled.

path Parameters

id required	string The id of the Cart.
line_id required	string The id of the Line Item.

Request Body schema: application/json

quantity

required

number

The quantity to set the Line Item to.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

Payload
JS Client
cURL

Content type

application/json

{"quantity": 0
}

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Delete a Payment Session

Deletes a Payment Session on a Cart. May be useful if a payment has failed.

path Parameters

id required	string The id of the Cart.
provider_id required	string The id of the Payment Provider used to create the Payment Session to be deleted.

Responses

Response Schema: application/json

object (Cart)

Represents a user cart

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The billing address's ID
completed_at required	string or null <date-time> The date with timezone at which the cart was completed.
context required	object or null Example: {"ip":"::1","user_agent":"PostmanRuntime/7.29.2"} The context of the cart which can include info like IP or user agent.
created_at required	string <date-time> The date with timezone at which the resource was created.
customer_id required	string or null Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The customer's ID
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
email required	string or null <email> The email associated with the cart
id required	string Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The cart's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of a cart in case of failure. Learn more how to use the idempotency key.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
payment_authorized_at required	string or null <date-time> The date with timezone at which the payment was authorized.
payment_id required	string or null Example: "pay_01G8ZCC5W42ZNY842124G7P5R9" The payment's ID if available
payment_session required	object or null The selected payment session in the cart.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The shipping address's ID
type required	string Default: "default" Enum: "default" "swap" "draft_order" "payment_link" "claim" The cart's type.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Address) An address.
	object (Address) An address.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Region) Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries.
	Array of objects (Discount) Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) Available if the relation `gift_cards` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
payment_sessions	Array of objects The payment sessions created on the cart.
payment	object or null Available if the relation `payment` is expanded.
	Array of objects (Shipping Method) The shipping methods added to the cart.
sales_channel_id	string or null Example: null The sales channel ID the cart is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
discount_total	integer Example: 800 The total of discount
item_tax_total	integer Example: 8000 The total of items with taxes
shipping_tax_total	integer Example: 1000 The total of shipping with taxes
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order associated with this cart is returned.
total	integer Example: 8200 The total amount of the cart
subtotal	integer Example: 8000 The subtotal of the cart
refundable_amount	integer Example: 8200 The amount that can be refunded
gift_card_total	integer Example: 0 The total of gift cards
gift_card_tax_total	integer Example: 0 The total of gift cards with taxes

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.carts.deletePaymentSession(cart_id, 'manual')
.then(({ cart }) => {
  console.log(cart.id);
});

Response samples

Content type

application/json

{"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"company": "Acme",
"first_name": "Arno",
"last_name": "Willms",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"country": {"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
},
"province": "Kentucky",
"postal_code": 72093,
"phone": 16128234334802,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"items": [{"id": null,
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"tax_lines": [ ],
"adjustments": [ ],
"original_item_id": null,
"order_edit_id": null,
"order_edit": { },
"title": null,
"description": null,
"thumbnail": null,
"is_return": null,
"is_giftcard": null,
"should_merge": null,
"allow_discounts": null,
"has_shipping": null,
"unit_price": null,
"variant_id": null,
"variant": null,
"quantity": null,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"refundable": null,
"subtotal": null,
"tax_total": null,
"total": null,
"original_total": null,
"original_tax_total": null,
"discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"tax_rates": [null
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [null
],
"tax_provider_id": null,
"tax_provider": {"id": null,
"is_installed": null
},
"payment_providers": [null
],
"fulfillment_providers": [null
],
"includes_tax": false,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"discounts": [{"id": null,
"code": null,
"is_dynamic": null,
"rule_id": null,
"rule": null,
"is_disabled": null,
"parent_discount_id": null,
"parent_discount": { },
"starts_at": null,
"ends_at": null,
"valid_duration": null,
"regions": [ ],
"usage_limit": null,
"usage_count": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"gift_cards": [{"id": null,
"code": null,
"value": null,
"balance": null,
"region_id": null,
"region": null,
"order_id": null,
"order": { },
"is_disabled": null,
"ends_at": null,
"tax_rate": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [{"id": null,
"shipping_option_id": null,
"order_id": null,
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": null,
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": null,
"tax_lines": [ ],
"price": null,
"data": { },
"includes_tax": null,
"subtotal": null,
"total": null,
"tax_total": null
}
],
"type": "default",
"completed_at": "2019-08-24T14:15:22Z",
"payment_authorized_at": "2019-08-24T14:15:22Z",
"idempotency_key": "string",
"context": {"ip": "::1",
"user_agent": "PostmanRuntime/7.29.2"
},
"sales_channel_id": null,
"sales_channel": {"id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
"name": "Market",
"description": "Multi-vendor market",
"is_disabled": false,
"locations": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"shipping_total": 1000,
"discount_total": 800,
"item_tax_total": 8000,
"shipping_tax_total": 1000,
"tax_total": 0,
"refunded_total": 0,
"total": 8200,
"subtotal": 8000,
"refundable_amount": 8200,
"gift_card_total": 0,
"gift_card_tax_total": 0
}
}

Medusa Storefront API (1.0.0)

Authentication

Cookie Session ID

How to Obtain the Cookie Session

Expanding Fields

Expanding One Relation

Expanding Multiple Relations

Prevent Expanding Relations

Selecting Fields

Selecting One Field

Selecting Multiple Fields

Retrieve Only the ID

Query Parameter Types

Strings

Integers

Boolean

Date and DateTime

Array

Object

Pagination

Query Parameters

Response Fields

Auth

Customer Login

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Customer Log out

Authorizations:

Responses

Request samples

Response samples

Get Current Customer

Authorizations:

Responses

Response Schema: application/json

Request samples

Response samples

Check if email exists

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Cart

Add a Shipping Method

path Parameters

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Calculate Cart Taxes

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Complete a Cart

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Create a Cart

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Create Payment Sessions

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Remove Discount

path Parameters