Auth
ENDPOINTS
POST/auth
DELETE/auth
GET/auth
GET/auth/:email
Authenticate Customer
POST/auth
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
emailstringrequired
The Customer's email.
passwordstringrequired
The Customer's password.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/auth \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"email":"test1@email.com","password":"example_auth_password"}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Log out
DELETE/auth
Destroys a Customer's authenticated session.
CURL EXAMPLE
Copy to clipboard
curl -X DELETE https://medusa-url.com/store/auth \
--header "Authorization: Bearer <ACCESS TOKEN>" Get Session
GET/auth
Gets the currently logged in Customer.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/auth \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Check if email has account
GET/auth/:email
Checks if a Customer with the given email has signed up.
Parameters
emailstringrequired
The Customer's email.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/auth/:email \
--header "Authorization: Bearer <ACCESS TOKEN>" Cart
Represents a user cart
ENDPOINTS
POST/carts/:id/shipping-methods
POST/carts/:id/complete
POST/carts
POST/carts/:id/line-items
POST/carts/:id/payment-sessions
DELETE/carts/:id/discounts/:code
DELETE/carts/:id/line-items/:line_id
POST/carts/:id/line-items/:line_id
DELETE/carts/:id/payment-sessions/:provider_id
POST/carts/:id/payment-sessions/:provider_id
GET/carts/:id
POST/carts/:id/payment-session
POST/store/carts/:id
Add a Shipping Method
POST/carts/:id/shipping-methods
Adds a Shipping Method to the Cart.
ParametersRequest body
idstringrequired
The cart id.
option_idstringrequired
id of the shipping option to create the method from
dataobject
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.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/shipping-methods \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"option_id":"example_cart_option_id"}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Complete a Cart
POST/carts/:id/complete
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.
Parameters
idstringrequired
The Cart id.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/complete \
--header "Authorization: Bearer <ACCESS TOKEN>" Create a Cart
POST/carts
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
region_idstring
The id of the Region to create the Cart in.
country_codestring
The 2 character ISO country code to create the Cart in.
itemsarray
An optional array of variant_id, quantity pairs to generate Line Items from.
contextobject
An optional object to provide context to the Cart. The context field is automatically populated with ip and user_agent
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"region_id":"region"}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Add a Line Item
POST/carts/:id/line-items
Generates a Line Item with a given Product Variant and adds it to the Cart
ParametersRequest body
idstringrequired
The id of the Cart to add the Line Item to.
variant_idstringrequired
The id of the Product Variant to generate the Line Item from.
quantityintegerrequired
The quantity of the Product Variant to add to the Line Item.
metadataobject
An optional key-value map with additional details about the Line Item.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/line-items \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"variant_id":"example_cart_variant_id","quantity":1000}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Initialize Payment Sessions
POST/carts/:id/payment-sessions
Creates Payment Sessions for each of the available Payment Providers in the Cart's Region.
Parameters
idstringrequired
The id of the Cart.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/payment-sessions \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Remove Discount from Cart
DELETE/carts/:id/discounts/:code
Removes a Discount from a Cart.
Parameters
idstringrequired
The id of the Cart.
codestringrequired
The unique Discount code.
CURL EXAMPLE
Copy to clipboard
curl -X DELETE https://medusa-url.com/store/carts/:id/discounts/:code \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Delete a Line Item
DELETE/carts/:id/line-items/:line_id
Removes a Line Item from a Cart.
Parameters
idstringrequired
The id of the Cart.
line_idstringrequired
The id of the Line Item.
CURL EXAMPLE
Copy to clipboard
curl -X DELETE https://medusa-url.com/store/carts/:id/line-items/:line_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Update a Line Item
POST/carts/:id/line-items/:line_id
Updates a Line Item if the desired quantity can be fulfilled.
ParametersRequest body
idstringrequired
The id of the Cart.
line_idstringrequired
The id of the Line Item.
quantityintegerrequired
The quantity to set the Line Item to.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/line-items/:line_id \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"quantity":1000}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Delete a Payment Session
DELETE/carts/:id/payment-sessions/:provider_id
Deletes a Payment Session on a Cart. May be useful if a payment has failed.
Parameters
idstringrequired
The id of the Cart.
provider_idstringrequired
The id of the Payment Provider used to create the Payment Session to be deleted.
CURL EXAMPLE
Copy to clipboard
curl -X DELETE https://medusa-url.com/store/carts/:id/payment-sessions/:provider_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Update a Payment Session
POST/carts/:id/payment-sessions/:provider_id
Updates a Payment Session with additional data.
ParametersRequest body
idstringrequired
The id of the Cart.
provider_idstringrequired
The id of the payment provider.
provider_idstringrequired
The id of the Payment Provider responsible for the Payment Session to update.
dataobjectrequired
The data to update the payment session with.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/payment-sessions/:provider_id \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"provider_id":"example_cart_provider_id","data":{}}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Retrieve a Cart
GET/carts/:id
Retrieves a Cart.
Parameters
idstringrequired
The id of the Cart.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/carts/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Select a Payment Session
POST/carts/:id/payment-session
Selects a Payment Session as the session intended to be used towards the completion of the Cart.
ParametersRequest body
idstringrequired
The id of the Cart.
provider_idstringrequired
The id of the Payment Provider.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/carts/:id/payment-session \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"provider_id":"example_cart_provider_id"}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Update a Cart"
POST/store/carts/:id
Updates a Cart.
ParametersRequest body
idstringrequired
The id of the Cart.
region_idstring
The id of the Region to create the Cart in.
country_codestring
The 2 character ISO country code to create the Cart in.
emailstring
An email to be used on the Cart.
billing_addressAddress
The Address to be used for billing purposes.
×
Show child attributesAddress
id
stringcustomer_id
stringcompany
stringfirst_name
stringlast_name
stringaddress_1
stringaddress_2
stringcity
stringcountry_code
stringcountry
shipping_addressAddress
The Address to be used for shipping.
×
Show child attributesAddress
id
stringcustomer_id
stringcompany
stringfirst_name
stringlast_name
stringaddress_1
stringaddress_2
stringcity
stringcountry_code
stringcountry
gift_cardsarray
An array of Gift Card codes to add to the Cart.
discountsarray
An array of Discount codes to add to the Cart.
customer_idstring
The id of the Customer to associate the Cart with.
contextobject
An optional object to provide context to the Cart.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/store/carts/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"region_id":"region"}'RESPONSE
{
"cart": {
"id": "cart_01F0YES82DA12W88KQ90EY6W4C",
"email": null,
"billing_address_id": null,
"billing_address": null,
"shipping_address_id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"shipping_address": {
"id": "addr_01F0YES82D4Y16JKGF0NFSSS3P",
"customer_id": null,
"company": null,
"first_name": null,
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.766Z",
"deleted_at": null,
"metadata": null
},
"items": [],
"region_id": "region",
"region": {
"id": "region",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"countries": [
{
"id": 236,
"iso_2": "us",
"iso_3": "usa",
"num_code": 840,
"name": "UNITED STATES",
"display_name": "United States",
"region_id": "region"
}
],
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:03.743Z",
"updated_at": "2021-03-16T21:24:03.743Z",
"deleted_at": null,
"metadata": null
},
"discounts": [],
"gift_cards": [],
"customer_id": null,
"payment_sessions": [],
"payment_id": null,
"payment": null,
"shipping_methods": [],
"type": "default",
"completed_at": null,
"created_at": "2021-03-16T21:24:03.766Z",
"updated_at": "2021-03-16T21:24:03.857Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": null,
"context": {
"ip": "::ffff:127.0.0.1",
"user_agent": "axios/0.21.1"
},
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"gift_card_total": 0,
"subtotal": 0,
"total": 0
}
}Collection
Product Collections represents a group of Products that are related.
ENDPOINTS
GET/collections/:id
GET/collections
Retrieve a Product Collection
GET/collections/:id
Retrieves a Product Collection.
Parameters
idstringrequired
The id of the Product Collection
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/collections/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"collection": {
"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"created_at": "2021-03-16T21:24:07.273Z",
"updated_at": "2021-03-16T21:24:07.273Z",
"deleted_at": null,
"metadata": null
}
}List Product Collections
GET/collections
Retrieve a list of Product Collection.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/collections \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"collection": {
"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"created_at": "2021-03-16T21:24:07.273Z",
"updated_at": "2021-03-16T21:24:07.273Z",
"deleted_at": null,
"metadata": null
}
}Customer
Represents a customer
ENDPOINTS
POST/customers/:id/addresses
POST/customers
DELETE/customers/:id/addresses/:address_id
GET/customers/me
POST/customers/me
GET/customers/me/payment-methods
GET/customers/me/orders
POST/customers/password-token
POST/customers/reset-password
POST/customers/me/addresses/:address_id
Add a Shipping Address
POST/customers/:id/addresses
Adds a Shipping Address to a Customer's saved addresses.
ParametersRequest body
idstringrequired
The Customer id.
addressAddress
The Address to add to the Customer.
×
Show child attributesAddress
id
stringcustomer_id
stringcompany
stringfirst_name
stringlast_name
stringaddress_1
stringaddress_2
stringcity
stringcountry_code
stringcountry
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers/:id/addresses \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"address":"example_customer_address"}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Create a Customer
POST/customers
Creates a Customer account.
Request body
emailstringrequired
The Customer's email address.
first_namestringrequired
The Customer's first name.
last_namestringrequired
The Customer's last name.
passwordstringrequired
The Customer's password for login.
phonestring
The Customer's phone number.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"email":"test1@email.com","first_name":null,"last_name":null,"password":"example_customer_password"}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Delete an Address
DELETE/customers/:id/addresses/:address_id
Removes an Address from the Customer's saved addresse.
Parameters
idstringrequired
The id of the Customer.
address_idstringrequired
The id of the Address to remove.
CURL EXAMPLE
Copy to clipboard
curl -X DELETE https://medusa-url.com/store/customers/:id/addresses/:address_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Retrieves a Customer
GET/customers/me
Retrieves a Customer - the Customer must be logged in to retrieve their details.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/customers/me \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Update Customer details
POST/customers/me
Updates a Customer's saved details.
Request body
first_namestring
The Customer's first name.
last_namestring
The Customer's last name.
billing_addressAddress
The Address to be used for billing purposes.
×
Show child attributesAddress
id
stringcustomer_id
stringcompany
stringfirst_name
stringlast_name
stringaddress_1
stringaddress_2
stringcity
stringcountry_code
stringcountry
passwordstring
The Customer's password.
phonestring
The Customer's phone number.
emailstring
The email of the customer.
metadataobject
Metadata about the customer.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers/me \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"first_name":null}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Retrieve saved payment methods
GET/customers/me/payment-methods
Retrieves a list of a Customer's saved payment methods. Payment methods are saved with Payment Providers and it is their responsibility to fetch saved methods.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/customers/me/payment-methods \
--header "Authorization: Bearer <ACCESS TOKEN>" Retrieve Customer Orders
GET/customers/me/orders
Retrieves a list of a Customer's Orders.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/customers/me/orders \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"payment_methods": [
{
"id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 1,
"cart_id": null,
"customer_id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"customer": {
"id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"email": "test@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"created_at": "2021-03-16T21:24:35.843Z",
"updated_at": "2021-03-16T21:24:35.843Z",
"deleted_at": null,
"metadata": null
},
"email": "test@email.com",
"billing_address": {
"id": "addr_01F0YET7CZZX0842X5AHQYAZ80",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"shipping_address": {
"id": "addr_01F0YET7CZDHXHXYJ3JTXPH4T7",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"region": {
"id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:35.839Z",
"updated_at": "2021-03-16T21:24:35.839Z",
"deleted_at": null,
"metadata": null
},
"currency_code": "usd",
"tax_rate": 0,
"discounts": [
{
"id": "test-discount",
"code": "TEST134",
"is_dynamic": false,
"rule_id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"rule": {
"id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"description": "Test Discount",
"type": "percentage",
"value": 10,
"allocation": "total",
"usage_limit": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"is_disabled": false,
"parent_discount_id": null,
"starts_at": "2021-03-16T21:24:35.871Z",
"ends_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
}
],
"gift_cards": [],
"shipping_methods": [
{
"id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
"shipping_option_id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"claim_order_id": null,
"cart_id": null,
"swap_id": null,
"return_id": null,
"shipping_option": {
"id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"name": "test-option",
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"provider_id": "test-ful",
"price_type": "flat_rate",
"amount": 1000,
"is_return": false,
"data": {},
"created_at": "2021-03-16T21:24:35.846Z",
"updated_at": "2021-03-16T21:24:35.846Z",
"deleted_at": null,
"metadata": null
},
"price": 1000,
"data": {}
}
],
"payments": [
{
"id": "test-payment",
"swap_id": null,
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"amount": 10000,
"currency_code": "usd",
"amount_refunded": 0,
"provider_id": "test",
"data": {},
"captured_at": null,
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"idempotency_key": null
}
],
"fulfillments": [],
"returns": [],
"claims": [],
"refunds": [],
"swaps": [],
"items": [
{
"id": "test-item",
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"swap_id": null,
"claim_order_id": null,
"title": "Line Item",
"description": "Line Item Desc",
"thumbnail": "https://test.js/1234",
"is_giftcard": false,
"should_merge": true,
"allow_discounts": true,
"has_shipping": null,
"unit_price": 8000,
"variant_id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"variant": {
"id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"title": "test variant",
"product_id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"product": {
"id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"title": "test product",
"subtitle": null,
"description": null,
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": null,
"type_id": null,
"created_at": "2021-03-16T21:24:35.818Z",
"updated_at": "2021-03-16T21:24:35.818Z",
"deleted_at": null,
"metadata": null
},
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 1,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"created_at": "2021-03-16T21:24:35.828Z",
"updated_at": "2021-03-16T21:24:35.828Z",
"deleted_at": null,
"metadata": null
},
"quantity": 1,
"fulfilled_quantity": 1,
"returned_quantity": null,
"shipped_quantity": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"refundable": 7200
}
],
"gift_card_transactions": [],
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"shipping_total": 1000,
"gift_card_total": 0,
"discount_total": 800,
"tax_total": 0,
"subtotal": 8000,
"total": 8200,
"refunded_total": 0,
"refundable_amount": 8200
}
]
}Creates a reset password token
POST/customers/password-token
Creates a reset password token to be used in a subsequent /reset-password request. The password token should be sent out of band e.g. via email and will not be returned.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers/password-token \
--header "Authorization: Bearer <ACCESS TOKEN>" Resets Customer password
POST/customers/reset-password
Resets a Customer's password using a password token created by a previous /password-token request.
Request body
emailstringrequired
The Customer's email.
tokenstringrequired
The password token created by a /password-token request.
passwordstringrequired
The new password to set for the Customer.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers/reset-password \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"email":"test1@email.com","token":"example_customer_token","password":"example_customer_password"}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Update a Shipping Address
POST/customers/me/addresses/:address_id
Updates a Customer's saved Shipping Address.
ParametersRequest body
address_idstringrequired
The id of the Address to update.
addressAddress
The updated Address.
×
Show child attributesAddress
id
stringcustomer_id
stringcompany
stringfirst_name
stringlast_name
stringaddress_1
stringaddress_2
stringcity
stringcountry_code
stringcountry
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/customers/me/addresses/:address_id \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"address":"example_customer_address"}'RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Gift Card
Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.
ENDPOINTS
GET/gift-cards/:code
Retrieve Gift Card by Code
GET/gift-cards/:code
Retrieves a Gift Card by its associated unqiue code.
Parameters
codestringrequired
The unique Gift Card code.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/gift-cards/:code \
--header "Authorization: Bearer <ACCESS TOKEN>" Order
Represents an order
ENDPOINTS
GET/orders/cart/:cart_id
GET/orders/:id
GET/orders
Retrieves Order by Cart id
GET/orders/cart/:cart_id
Retrieves an Order by the id of the Cart that was used to create the Order.
Parameters
cart_idstringrequired
The id of Cart.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/orders/cart/:cart_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"order": {
"id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 1,
"cart_id": null,
"customer_id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"customer": {
"id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"email": "test@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"created_at": "2021-03-16T21:24:35.843Z",
"updated_at": "2021-03-16T21:24:35.843Z",
"deleted_at": null,
"metadata": null
},
"email": "test@email.com",
"billing_address": {
"id": "addr_01F0YET7CZZX0842X5AHQYAZ80",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"shipping_address": {
"id": "addr_01F0YET7CZDHXHXYJ3JTXPH4T7",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"region": {
"id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:35.839Z",
"updated_at": "2021-03-16T21:24:35.839Z",
"deleted_at": null,
"metadata": null
},
"currency_code": "usd",
"tax_rate": 0,
"discounts": [
{
"id": "test-discount",
"code": "TEST134",
"is_dynamic": false,
"rule_id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"rule": {
"id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"description": "Test Discount",
"type": "percentage",
"value": 10,
"allocation": "total",
"usage_limit": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"is_disabled": false,
"parent_discount_id": null,
"starts_at": "2021-03-16T21:24:35.871Z",
"ends_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
}
],
"gift_cards": [],
"shipping_methods": [
{
"id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
"shipping_option_id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"claim_order_id": null,
"cart_id": null,
"swap_id": null,
"return_id": null,
"shipping_option": {
"id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"name": "test-option",
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"provider_id": "test-ful",
"price_type": "flat_rate",
"amount": 1000,
"is_return": false,
"data": {},
"created_at": "2021-03-16T21:24:35.846Z",
"updated_at": "2021-03-16T21:24:35.846Z",
"deleted_at": null,
"metadata": null
},
"price": 1000,
"data": {}
}
],
"payments": [
{
"id": "test-payment",
"swap_id": null,
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"amount": 10000,
"currency_code": "usd",
"amount_refunded": 0,
"provider_id": "test",
"data": {},
"captured_at": null,
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"idempotency_key": null
}
],
"fulfillments": [],
"returns": [],
"claims": [],
"refunds": [],
"swaps": [],
"items": [
{
"id": "test-item",
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"swap_id": null,
"claim_order_id": null,
"title": "Line Item",
"description": "Line Item Desc",
"thumbnail": "https://test.js/1234",
"is_giftcard": false,
"should_merge": true,
"allow_discounts": true,
"has_shipping": null,
"unit_price": 8000,
"variant_id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"variant": {
"id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"title": "test variant",
"product_id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"product": {
"id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"title": "test product",
"subtitle": null,
"description": null,
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": null,
"type_id": null,
"created_at": "2021-03-16T21:24:35.818Z",
"updated_at": "2021-03-16T21:24:35.818Z",
"deleted_at": null,
"metadata": null
},
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 1,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"created_at": "2021-03-16T21:24:35.828Z",
"updated_at": "2021-03-16T21:24:35.828Z",
"deleted_at": null,
"metadata": null
},
"quantity": 1,
"fulfilled_quantity": 1,
"returned_quantity": null,
"shipped_quantity": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"refundable": 7200
}
],
"gift_card_transactions": [],
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"shipping_total": 1000,
"gift_card_total": 0,
"discount_total": 800,
"tax_total": 0,
"subtotal": 8000,
"total": 8200,
"refunded_total": 0,
"refundable_amount": 8200
}
}Retrieves an Order
GET/orders/:id
Retrieves an Order
Parameters
idstringrequired
The id of the Order.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/orders/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"customer": {
"id": "cus_01F0YESQXFZ5WKMHTXJ4JDPBDZ",
"email": "test1@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"orders": [],
"created_at": "2021-03-16T21:24:20.015Z",
"updated_at": "2021-03-16T21:24:20.015Z",
"deleted_at": null,
"metadata": null
}
}Look Up an Order
GET/orders
Looks for an Order with a given display_id, email pair. The display_id, email pair must match in order for the Order to be returned.
Parameters
display_idnumberrequired
The display id given to the Order.
emailstringrequired
The email of the Order with the given display_id.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/orders \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"order": {
"id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"display_id": 1,
"cart_id": null,
"customer_id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"customer": {
"id": "cus_01F0YET7C3H3D5M8QPNPP5CDAX",
"email": "test@email.com",
"first_name": null,
"last_name": null,
"billing_address_id": null,
"password_hash": null,
"phone": null,
"has_account": false,
"created_at": "2021-03-16T21:24:35.843Z",
"updated_at": "2021-03-16T21:24:35.843Z",
"deleted_at": null,
"metadata": null
},
"email": "test@email.com",
"billing_address": {
"id": "addr_01F0YET7CZZX0842X5AHQYAZ80",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": null,
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"shipping_address": {
"id": "addr_01F0YET7CZDHXHXYJ3JTXPH4T7",
"customer_id": null,
"company": null,
"first_name": "lebron",
"last_name": null,
"address_1": null,
"address_2": null,
"city": null,
"country_code": "us",
"province": null,
"postal_code": null,
"phone": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"region": {
"id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [],
"created_at": "2021-03-16T21:24:35.839Z",
"updated_at": "2021-03-16T21:24:35.839Z",
"deleted_at": null,
"metadata": null
},
"currency_code": "usd",
"tax_rate": 0,
"discounts": [
{
"id": "test-discount",
"code": "TEST134",
"is_dynamic": false,
"rule_id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"rule": {
"id": "dru_01F0YET7CZQDGWTFQYY8T4KYRZ",
"description": "Test Discount",
"type": "percentage",
"value": 10,
"allocation": "total",
"usage_limit": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
},
"is_disabled": false,
"parent_discount_id": null,
"starts_at": "2021-03-16T21:24:35.871Z",
"ends_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"deleted_at": null,
"metadata": null
}
],
"gift_cards": [],
"shipping_methods": [
{
"id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
"shipping_option_id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"claim_order_id": null,
"cart_id": null,
"swap_id": null,
"return_id": null,
"shipping_option": {
"id": "so_01F0YET7C758MMXF1WNVCPGKZJ",
"name": "test-option",
"region_id": "reg_01F0YET7BZTARY9MKN1SJ7AAXF",
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"provider_id": "test-ful",
"price_type": "flat_rate",
"amount": 1000,
"is_return": false,
"data": {},
"created_at": "2021-03-16T21:24:35.846Z",
"updated_at": "2021-03-16T21:24:35.846Z",
"deleted_at": null,
"metadata": null
},
"price": 1000,
"data": {}
}
],
"payments": [
{
"id": "test-payment",
"swap_id": null,
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"amount": 10000,
"currency_code": "usd",
"amount_refunded": 0,
"provider_id": "test",
"data": {},
"captured_at": null,
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"idempotency_key": null
}
],
"fulfillments": [],
"returns": [],
"claims": [],
"refunds": [],
"swaps": [],
"items": [
{
"id": "test-item",
"cart_id": null,
"order_id": "order_01F0YET7CZ741ECWG1J3N34RXF",
"swap_id": null,
"claim_order_id": null,
"title": "Line Item",
"description": "Line Item Desc",
"thumbnail": "https://test.js/1234",
"is_giftcard": false,
"should_merge": true,
"allow_discounts": true,
"has_shipping": null,
"unit_price": 8000,
"variant_id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"variant": {
"id": "variant_01F0YET7BMD9FGWA5NTPBWT2SS",
"title": "test variant",
"product_id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"product": {
"id": "prod_01F0YET7BA4AQ8WEK687BNWP3N",
"title": "test product",
"subtitle": null,
"description": null,
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": null,
"type_id": null,
"created_at": "2021-03-16T21:24:35.818Z",
"updated_at": "2021-03-16T21:24:35.818Z",
"deleted_at": null,
"metadata": null
},
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 1,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"created_at": "2021-03-16T21:24:35.828Z",
"updated_at": "2021-03-16T21:24:35.828Z",
"deleted_at": null,
"metadata": null
},
"quantity": 1,
"fulfilled_quantity": 1,
"returned_quantity": null,
"shipped_quantity": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"refundable": 7200
}
],
"gift_card_transactions": [],
"canceled_at": null,
"created_at": "2021-03-16T21:24:35.871Z",
"updated_at": "2021-03-16T21:24:35.871Z",
"metadata": null,
"shipping_total": 1000,
"gift_card_total": 0,
"discount_total": 800,
"tax_total": 0,
"subtotal": 8000,
"total": 8200,
"refunded_total": 0,
"refundable_amount": 8200
}
}Product
Products are a grouping of Product Variants that have common properties such as images and descriptions. Products can have multiple options which define the properties that Product Variants differ by.
ENDPOINTS
GET/products/:id
GET/products
Retrieves a Product
GET/products/:id
Retrieves a Product.
Parameters
idstringrequired
The id of the Product.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/products/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"product": {
"id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"title": "Test product",
"subtitle": null,
"description": "test-product-description",
"handle": "test-product",
"is_giftcard": false,
"images": [],
"thumbnail": null,
"options": [
{
"id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
"title": "size",
"product_id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
{
"id": "opt_01F0YESHQBV8MMNN4V7WSDMH6G",
"title": "color",
"product_id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"variants": [
{
"id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"title": "Test variant",
"product_id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"product": {
"id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"title": "Test product",
"subtitle": null,
"description": "test-product-description",
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YESHMKRB4V3B7F6MVQHGNN",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "test-collection",
"type_id": "test-type",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
"prices": [
{
"id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
"currency_code": "usd",
"amount": 100,
"sale_amount": null,
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"region_id": null,
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null
}
],
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 10,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [
{
"id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
"value": "large",
"option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
{
"id": "optval_01F0YESHR7N2GHM1RN3GKYPN6P",
"value": "green",
"option_id": "opt_01F0YESHQBV8MMNN4V7WSDMH6G",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"profile_id": "sp_01F0YESHMKRB4V3B7F6MVQHGNN",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "test-collection",
"collection": {
"id": "test-collection",
"title": "Test collection",
"handle": null,
"created_at": "2021-03-16T21:24:13.603Z",
"updated_at": "2021-03-16T21:24:13.603Z",
"deleted_at": null,
"metadata": null
},
"type_id": "test-type",
"type": {
"id": "test-type",
"value": "test-type",
"created_at": "2021-03-16T21:24:13.613Z",
"updated_at": "2021-03-16T21:24:13.613Z",
"deleted_at": null,
"metadata": null
},
"tags": [
{
"id": "tag1",
"value": "123",
"created_at": "2021-03-16T21:24:13.609Z",
"updated_at": "2021-03-16T21:24:13.609Z",
"deleted_at": null,
"metadata": null
},
{
"id": "ptag_01F0YESHPZYY3H4SJ3A5918SBN",
"value": "456",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"metadata": null
}
}List Products
GET/products
Retrieves a list of Products.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/products \
--header "Authorization: Bearer <ACCESS TOKEN>" 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.
ENDPOINTS
GET/regions/:id
GET/regions
Retrieves a Region
GET/regions/:id
Retrieves a Region.
Parameters
idstringrequired
The id of the Region.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/regions/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"region": {
"id": "reg_01F0YES4R67TXXC1QBQ8P54A8Y",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [
{
"id": "test-ful",
"is_installed": true
}
],
"created_at": "2021-03-16T21:24:00.389Z",
"updated_at": "2021-03-16T21:24:00.389Z",
"deleted_at": null,
"metadata": null
}
}List Regions
GET/regions
Retrieves a list of Regions.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/regions \
--header "Authorization: Bearer <ACCESS TOKEN>" Return Reason
ENDPOINTS
GET/return-reasons/:id
GET/return-reasons
Retrieve a Return Reason
GET/return-reasons/:id
Retrieves a Return Reason.
Parameters
idstringrequired
The id of the Return Reason.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/return-reasons/:id \
--header "Authorization: Bearer <ACCESS TOKEN>" List Return Reasons
GET/return-reasons
Retrieves a list of Return Reasons.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/return-reasons \
--header "Authorization: Bearer <ACCESS TOKEN>" Return
Return orders hold information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can be used as part of a Swap.
ENDPOINTS
POST/returns
Create Return
POST/returns
Creates a Return for an Order.
Request body
order_idstring
The id of the Order to create the Return from.
itemsarray
The items to include in the Return.
return_shippingobject
If the Return is to be handled by the store operator the Customer can choose a Return Shipping Method. Alternatvely the Customer can handle the Return themselves.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/returns \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"order_id":"order_01F0YET7RD6NWQTEM0ZN5DRRVD"}'RESPONSE
{
"return": {
"id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
"status": "requested",
"items": [
{
"return_id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
"item_id": "test-item",
"quantity": 1,
"is_requested": true,
"requested_quantity": 1,
"received_quantity": null,
"reason_id": null,
"reason": null,
"note": null,
"metadata": null
}
],
"swap_id": null,
"claim_order_id": null,
"order_id": "order_01F0YET7RD6NWQTEM0ZN5DRRVD",
"shipping_method": null,
"shipping_data": null,
"refund_amount": 7200,
"received_at": null,
"created_at": "2021-03-16T21:24:36.381Z",
"updated_at": "2021-03-16T21:24:36.381Z",
"metadata": null,
"idempotency_key": "f3dee891-7a24-4e34-9071-62606035563d"
}
}Shipping Option
Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.
ENDPOINTS
GET/shipping-options
GET/shipping-options/:cart_id
Retrieve Shipping Options
GET/shipping-options
Retrieves a list of Shipping Options.
Parameters
is_returnboolean
Whether return Shipping Options should be included. By default all Shipping Options are returned.
product_idsstring
A comma separated list of Product ids to filter Shipping Options by.
region_idstring
the Region to retrieve Shipping Options from.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/shipping-options \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"shipping_options": [
{
"id": "so_01F0YES4T6ZHH52Z4KZEDT1312",
"name": "Free Shipping",
"region_id": "reg_01F0YES4R67TXXC1QBQ8P54A8Y",
"region": {
"id": "reg_01F0YES4R67TXXC1QBQ8P54A8Y",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [
{
"id": "test-ful",
"is_installed": true
}
],
"created_at": "2021-03-16T21:24:00.389Z",
"updated_at": "2021-03-16T21:24:00.389Z",
"deleted_at": null,
"metadata": null
},
"profile_id": "sp_01F0YES4Q77FGG18GPFWW5BZP9",
"profile": {
"id": "sp_01F0YES4Q77FGG18GPFWW5BZP9",
"name": "Default Shipping Profile",
"type": "default",
"created_at": "2021-03-16T21:24:00.307Z",
"updated_at": "2021-03-16T21:24:00.307Z",
"deleted_at": null,
"metadata": null
},
"provider_id": "test-ful",
"price_type": "flat_rate",
"amount": 100,
"is_return": false,
"requirements": [],
"data": {},
"created_at": "2021-03-16T21:24:00.439Z",
"updated_at": "2021-03-16T21:24:00.439Z",
"deleted_at": null,
"metadata": null
}
]
}Retrieve Shipping Options for Cart
GET/shipping-options/:cart_id
Retrieves a list of Shipping Options available to a cart.
Parameters
cart_idstringrequired
The id of the Cart.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/shipping-options/:cart_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"shipping_options": [
{
"id": "so_01F0YES4T6ZHH52Z4KZEDT1312",
"name": "Free Shipping",
"region_id": "reg_01F0YES4R67TXXC1QBQ8P54A8Y",
"region": {
"id": "reg_01F0YES4R67TXXC1QBQ8P54A8Y",
"name": "Test Region",
"currency_code": "usd",
"tax_rate": "0",
"tax_code": null,
"payment_providers": [],
"fulfillment_providers": [
{
"id": "test-ful",
"is_installed": true
}
],
"created_at": "2021-03-16T21:24:00.389Z",
"updated_at": "2021-03-16T21:24:00.389Z",
"deleted_at": null,
"metadata": null
},
"profile_id": "sp_01F0YES4Q77FGG18GPFWW5BZP9",
"profile": {
"id": "sp_01F0YES4Q77FGG18GPFWW5BZP9",
"name": "Default Shipping Profile",
"type": "default",
"created_at": "2021-03-16T21:24:00.307Z",
"updated_at": "2021-03-16T21:24:00.307Z",
"deleted_at": null,
"metadata": null
},
"provider_id": "test-ful",
"price_type": "flat_rate",
"amount": 100,
"is_return": false,
"requirements": [],
"data": {},
"created_at": "2021-03-16T21:24:00.439Z",
"updated_at": "2021-03-16T21:24:00.439Z",
"deleted_at": null,
"metadata": null
}
]
}Swap
Swaps can be created when a Customer wishes to exchange Products that they have purchased to different Products. Swaps consist of a Return of previously purchased Products and a Fulfillment of new Products, the amount paid for the Products being returned will be used towards payment for the new Products. In the case where the amount paid for the the Products being returned exceed the amount to be paid for the new Products, a Refund will be issued for the difference.
ENDPOINTS
POST/swaps
GET/swaps/:cart_id
Create a Swap
POST/swaps
Creates a Swap on an Order by providing some items to return along with some items to send back
Request body
order_idstring
The id of the Order to create the Swap for.
return_itemsarray
The items to include in the Return.
return_shipping_optionstring
The id of the Shipping Option to create the Shipping Method from.
additional_itemsarray
The items to exchange the returned items to.
CURL EXAMPLE
Copy to clipboard
curl -X POST https://medusa-url.com/store/swaps \
--header "Authorization: Bearer <ACCESS TOKEN>" \
--header "content-type: application/json" \
--data '{"order_id":"order_01F0YET82SR6NB8K61TNRN36FW"}'RESPONSE
{
"swap": {
"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01F0YET82SR6NB8K61TNRN36FW",
"additional_items": [
{
"id": "item_01F0YET86YR1J3GX155E9R81A3",
"cart_id": "cart_01F0YET896KVZ17Y2QDVT28QFE",
"order_id": null,
"swap_id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"claim_order_id": null,
"title": "test product",
"description": "test variant",
"thumbnail": null,
"is_giftcard": false,
"should_merge": true,
"allow_discounts": true,
"has_shipping": null,
"unit_price": 8000,
"variant_id": "variant_01F0YET825M92TKN1ZGAVBPX1B",
"variant": {
"id": "variant_01F0YET825M92TKN1ZGAVBPX1B",
"title": "test variant",
"product_id": "prod_01F0YET8213X0J501ZZHZ56Y7Y",
"product": {
"id": "prod_01F0YET8213X0J501ZZHZ56Y7Y",
"title": "test product",
"subtitle": null,
"description": null,
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": null,
"type_id": null,
"created_at": "2021-03-16T21:24:36.545Z",
"updated_at": "2021-03-16T21:24:36.545Z",
"deleted_at": null,
"metadata": null
},
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 1,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"created_at": "2021-03-16T21:24:36.549Z",
"updated_at": "2021-03-16T21:24:36.549Z",
"deleted_at": null,
"metadata": null
},
"quantity": 2,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"metadata": {}
}
],
"return_order": {
"id": "ret_01F0YET873ZAXQ7PYVKVFMT9FP",
"status": "requested",
"items": [
{
"return_id": "ret_01F0YET873ZAXQ7PYVKVFMT9FP",
"item_id": "test-item",
"quantity": 1,
"is_requested": true,
"requested_quantity": 1,
"received_quantity": null,
"reason_id": null,
"reason": null,
"note": null,
"metadata": null
}
],
"swap_id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"claim_order_id": null,
"order_id": null,
"shipping_method": null,
"shipping_data": null,
"refund_amount": 7200,
"received_at": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"metadata": null,
"idempotency_key": null
},
"fulfillments": [],
"payment": null,
"difference_due": null,
"shipping_address_id": null,
"shipping_address": null,
"shipping_methods": [],
"cart_id": "cart_01F0YET896KVZ17Y2QDVT28QFE",
"confirmed_at": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": "10804103-2f4f-41ef-b44e-7049459f157d"
}
}Retrieve Swap by Cart id
GET/swaps/:cart_id
Retrieves a Swap by the id of the Cart used to confirm the Swap.
Parameters
cart_idstringrequired
The id of the Cart
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/swaps/:cart_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"swap": {
"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01F0YET82SR6NB8K61TNRN36FW",
"additional_items": [
{
"id": "item_01F0YET86YR1J3GX155E9R81A3",
"cart_id": "cart_01F0YET896KVZ17Y2QDVT28QFE",
"order_id": null,
"swap_id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"claim_order_id": null,
"title": "test product",
"description": "test variant",
"thumbnail": null,
"is_giftcard": false,
"should_merge": true,
"allow_discounts": true,
"has_shipping": null,
"unit_price": 8000,
"variant_id": "variant_01F0YET825M92TKN1ZGAVBPX1B",
"variant": {
"id": "variant_01F0YET825M92TKN1ZGAVBPX1B",
"title": "test variant",
"product_id": "prod_01F0YET8213X0J501ZZHZ56Y7Y",
"product": {
"id": "prod_01F0YET8213X0J501ZZHZ56Y7Y",
"title": "test product",
"subtitle": null,
"description": null,
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YET7AF62TCC9CMWK5TXXAQ",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": null,
"type_id": null,
"created_at": "2021-03-16T21:24:36.545Z",
"updated_at": "2021-03-16T21:24:36.545Z",
"deleted_at": null,
"metadata": null
},
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 1,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"created_at": "2021-03-16T21:24:36.549Z",
"updated_at": "2021-03-16T21:24:36.549Z",
"deleted_at": null,
"metadata": null
},
"quantity": 2,
"fulfilled_quantity": null,
"returned_quantity": null,
"shipped_quantity": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"metadata": {}
}
],
"return_order": {
"id": "ret_01F0YET873ZAXQ7PYVKVFMT9FP",
"status": "requested",
"items": [
{
"return_id": "ret_01F0YET873ZAXQ7PYVKVFMT9FP",
"item_id": "test-item",
"quantity": 1,
"is_requested": true,
"requested_quantity": 1,
"received_quantity": null,
"reason_id": null,
"reason": null,
"note": null,
"metadata": null
}
],
"swap_id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"claim_order_id": null,
"order_id": null,
"shipping_method": null,
"shipping_data": null,
"refund_amount": 7200,
"received_at": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"metadata": null,
"idempotency_key": null
},
"fulfillments": [],
"payment": null,
"difference_due": null,
"shipping_address_id": null,
"shipping_address": null,
"shipping_methods": [],
"cart_id": "cart_01F0YET896KVZ17Y2QDVT28QFE",
"confirmed_at": null,
"created_at": "2021-03-16T21:24:36.659Z",
"updated_at": "2021-03-16T21:24:36.659Z",
"deleted_at": null,
"metadata": null,
"idempotency_key": "10804103-2f4f-41ef-b44e-7049459f157d"
}
}Product Variant
Product Variants represent a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations.
ENDPOINTS
GET/variants/:variant_id
GET/variants
Retrieve a Product Variant
GET/variants/:variant_id
Retrieves a Product Variant by id
Parameters
variant_idstringrequired
The id of the Product Variant.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/variants/:variant_id \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"variant": {
"id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"title": "Test variant",
"product_id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"product": {
"id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"title": "Test product",
"subtitle": null,
"description": "test-product-description",
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YESHMKRB4V3B7F6MVQHGNN",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "test-collection",
"type_id": "test-type",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
"prices": [
{
"id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
"currency_code": "usd",
"amount": 100,
"sale_amount": null,
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"region_id": null,
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null
}
],
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 10,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [
{
"id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
"value": "large",
"option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
{
"id": "optval_01F0YESHR7N2GHM1RN3GKYPN6P",
"value": "green",
"option_id": "opt_01F0YESHQBV8MMNN4V7WSDMH6G",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
}Retrieve Product Variants
GET/variants
Retrieves a list of Product Variants
Parameters
idsstring
A comma separated list of Product Variant ids to filter by.
CURL EXAMPLE
Copy to clipboard
curl -X GET https://medusa-url.com/store/variants \
--header "Authorization: Bearer <ACCESS TOKEN>" RESPONSE
{
"variants": [
{
"id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"title": "Test variant",
"product_id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"product": {
"id": "prod_01F0YESHQ27Y31CAMD0NV6W9YP",
"title": "Test product",
"subtitle": null,
"description": "test-product-description",
"handle": "test-product",
"is_giftcard": false,
"thumbnail": null,
"profile_id": "sp_01F0YESHMKRB4V3B7F6MVQHGNN",
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "test-collection",
"type_id": "test-type",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
"prices": [
{
"id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
"currency_code": "usd",
"amount": 100,
"sale_amount": null,
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"region_id": null,
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null
}
],
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"inventory_quantity": 10,
"allow_backorder": false,
"manage_inventory": true,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [
{
"id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
"value": "large",
"option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
},
{
"id": "optval_01F0YESHR7N2GHM1RN3GKYPN6P",
"value": "green",
"option_id": "opt_01F0YESHQBV8MMNN4V7WSDMH6G",
"variant_id": "variant_01F0YESHR7P2YAYBDBY5B6X3PK",
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
],
"created_at": "2021-03-16T21:24:13.657Z",
"updated_at": "2021-03-16T21:24:13.657Z",
"deleted_at": null,
"metadata": null
}
]
}