Medusa Storefront API (1.0.0)

Download OpenAPI specification:Download

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.

Sort Order

The order field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their created_at attribute by setting order to created_at:

curl "http://localhost:9000/list/products?order=created_at"

By default, the sort direction will be ascending. To change it to descending, pass a dash (-) before the attribute name. For example:

curl "http://localhost:9000/list/products?order=-created_at"

This sorts the products by their created_at attribute in the descending order.

Auth

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

Get Current Customer

Gets the currently logged in Customer.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

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"
}
}
}

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

required

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"
}

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

required

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
}

Carts

Cart endpoints that allow handling carts in Medusa.

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

required

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 rounded
raw_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,
"raw_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,
"raw_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
}
}

Get a Cart

Retrieves a Cart.

path Parameters

required

string

The id of the Cart.

Responses

Response Schema: application/json

required

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 rounded
raw_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.retrieve(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,
"raw_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,
"raw_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 Cart

Updates a Cart.

path Parameters

required

string

The id of the Cart.

Request Body schema: application/json

region_id	string The id of the Region to create the Cart in.
country_code	string The 2 character ISO country code to create the Cart in. See a list of codes.
email	string <email> An email to be used on the Cart.
sales_channel_id	string The ID of the Sales channel to update the Cart with.
	AddressPayload (object) or string The Address to be used for billing purposes.
	AddressPayload (object) or string The Address to be used for shipping.
	Array of objects An array of Gift Card codes to add to the Cart.
	Array of objects An array of Discount codes to add to the Cart.
customer_id	string The ID of the Customer to associate the Cart with.
context	object Example: {"ip":"::1","user_agent":"Chrome"} An optional object to provide context to the Cart.

Responses

Response Schema: application/json

required

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 rounded
raw_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",
"country_code": "string",
"email": "user@example.com",
"sales_channel_id": "string",
"billing_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"shipping_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"gift_cards": [{"code": "string"
}
],
"discounts": [{"code": "string"
}
],
"customer_id": "string",
"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,
"raw_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,
"raw_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 required	string Enum: "order" "cart" "swap" The type of the data property.
required	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,
"raw_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,
"raw_discount_total": 800,
"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,
"raw_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"
}
}
}

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

required

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 rounded
raw_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,
"raw_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,
"raw_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
}
}

Add a Line Item

Generates a Line Item with a given Product Variant and adds it to the Cart

path Parameters

required

string

The id of the Cart to add the Line Item to.

Request Body schema: application/json

variant_id required	string The id of the Product Variant to generate the Line Item from.
quantity required	number The quantity of the Product Variant to add to the Line Item.
metadata	object An optional key-value map with additional details about the Line Item.

Responses

Response Schema: application/json

required

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 rounded
raw_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

{"variant_id": "string",
"quantity": 0,
"metadata": { }
}

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,
"raw_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,
"raw_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

required

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 rounded
raw_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,
"raw_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,
"raw_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

required

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 rounded
raw_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,
"raw_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,
"raw_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
}
}

Select a Payment Session

Selects a Payment Session as the session intended to be used towards the completion of the Cart.

path Parameters

required

string

The ID of the Cart.

Request Body schema: application/json

provider_id

required

string

The ID of the Payment Provider.

Responses

Response Schema: application/json

required

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 rounded
raw_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

{"provider_id": "string"
}

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,
"raw_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,
"raw_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

required

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 rounded
raw_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,
"raw_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,
"raw_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 Payment Session

Updates a Payment Session with additional data.

path Parameters

id required	string The id of the Cart.
provider_id required	string The id of the payment provider.

Request Body schema: application/json

data

required

object

The data to update the payment session with.

Responses

Response Schema: application/json

required

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 rounded
raw_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

{"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,
"raw_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,
"raw_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

required

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 rounded
raw_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,
"raw_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,
"raw_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
}
}

Refresh a Payment Session

Refreshes a Payment Session to ensure that it is in sync with the Cart - this is usually not necessary.

path Parameters

id required	string The id of the Cart.
provider_id required	string The id of the Payment Provider that created the Payment Session to be refreshed.

Responses

Response Schema: application/json

required

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 rounded
raw_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.refreshPaymentSession(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,
"raw_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,
"raw_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
}
}

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

required

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 rounded
raw_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,
"raw_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,
"raw_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

required

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 rounded
raw_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,
"raw_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,
"raw_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
}
}

Collections

Collection endpoints that allow handling collections in Medusa.

List Collections

Retrieve a list of Product Collection.

query Parameters

offset	integer Default: 0 The number of collections to skip before starting to collect the collections set
limit	integer Default: 10 The number of collections to return
handle	Array of strings Filter by the collection handle
	object Date comparison for when resulting collections were created.
	object Date comparison for when resulting collections were updated.

Responses

Response Schema: application/json

required	Array of objects (Product Collection)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.collections.list()
.then(({ collections, limit, offset, count }) => {
  console.log(collections.length);
});

Response samples

Content type

application/json

{"collections": [{"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get a Collection

Retrieves a Product Collection.

path Parameters

required

string

The id of the Product Collection

Responses

Response Schema: application/json

required

object (Product Collection)

Product Collections represents a group of Products that are related.

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.
handle required	string or null Example: "summer-collection" A unique string that identifies the Product Collection - can for example be used in slug structures.
id required	string Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG" The product collection's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
title required	string Example: "Summer Collection" The title that the Product Collection is identified by.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
products	Array of objects The Products contained in the Product Collection. Available if the relation `products` is expanded.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.collections.retrieve(collection_id)
.then(({ collection }) => {
  console.log(collection.id);
});

Response samples

Content type

application/json

{"collection": {"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Customers

Customer endpoints that allow handling customers in Medusa.

Create a Customer

Creates a Customer account.

Request Body schema: application/json

first_name required	string The Customer's first name.
last_name required	string The Customer's last name.
email required	string <email> The email of the customer.
password required	string <password> The Customer's password.
phone	string The Customer's phone number.

Responses

Response Schema: application/json

required

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

{"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"password": "pa$$word",
"phone": "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"
}
}
}

Get a Customer

Retrieves a Customer - the Customer must be logged in to retrieve their details.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

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.customers.retrieve()
.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"
}
}
}

Update Customer

Updates a Customer's saved details.

Authorizations:

Cookie Session ID

Request Body schema: application/json

first_name	string The Customer's first name.
last_name	string The Customer's last name.
	AddressPayload (object) or string The Address to be used for billing purposes.
password	string The Customer's password.
phone	string The Customer's phone number.
email	string The email of the customer.
metadata	object Metadata about the customer.

Responses

Response Schema: application/json

required

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

{"first_name": "string",
"last_name": "string",
"billing_address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
},
"password": "string",
"phone": "string",
"email": "string",
"metadata": { }
}

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"
}
}
}

Add a Shipping Address

Adds a Shipping Address to a Customer's saved addresses.

Authorizations:

Cookie Session ID

Request Body schema: application/json

required

object (AddressCreatePayload)

Address fields used when creating an address.

first_name required	string Example: "Arno" First name
last_name required	string Example: "Willms" Last name
address_1 required	string Example: "14433 Kemmer Court" Address line 1
city required	string Example: "South Geoffreyview" City
country_code required	string Example: "st" The 2 character ISO code of the country in lower case See a list of codes.
postal_code required	string Example: 72093 Postal Code
phone	string Example: 16128234334802 Phone Number
company	string
address_2	string Example: "Suite 369" Address line 2
province	string Example: "Kentucky" Province
metadata	object Example: {"car":"white"} An optional key-value map with additional details

Responses

Response Schema: application/json

required

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

{"address": {"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
}
}

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"
}
}
}

Update a Shipping Address

Updates a Customer's saved Shipping Address.

Authorizations:

Cookie Session ID

path Parameters

address_id

required

string

The id of the Address to update.

Request Body schema: application/json

Any of

first_name	string Example: "Arno" First name
last_name	string Example: "Willms" Last name
phone	string Example: 16128234334802 Phone Number
company	string
address_1	string Example: "14433 Kemmer Court" Address line 1
address_2	string Example: "Suite 369" Address line 2
city	string Example: "South Geoffreyview" City
country_code	string Example: "st" The 2 character ISO code of the country in lower case See a list of codes.
province	string Example: "Kentucky" Province
postal_code	string Example: 72093 Postal Code
metadata	object Example: {"car":"white"} An optional key-value map with additional details

Responses

Response Schema: application/json

required

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

{"first_name": "Arno",
"last_name": "Willms",
"phone": 16128234334802,
"company": "string",
"address_1": "14433 Kemmer Court",
"address_2": "Suite 369",
"city": "South Geoffreyview",
"country_code": "st",
"province": "Kentucky",
"postal_code": 72093,
"metadata": {"car": "white"
}
}

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"
}
}
}

Delete an Address

Removes an Address from the Customer's saved addresses.

Authorizations:

Cookie Session ID

path Parameters

address_id

required

string

The id of the Address to remove.

Responses

Response Schema: application/json

required

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.customers.addresses.deleteAddress(address_id)
.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"
}
}
}

List Orders

Retrieves a list of a Customer's Orders.

Authorizations:

Cookie Session ID

query Parameters

q	string Query used for searching orders.
id	string Id of the order to search for.
status	Array of strings Status to search for.
fulfillment_status	Array of strings Fulfillment status to search for.
payment_status	Array of strings Payment status to search for.
display_id	string Display id to search for.
cart_id	string to search for.
email	string to search for.
region_id	string to search for.
currency_code	string The 3 character ISO currency code to set prices based on. See a list of codes.
tax_rate	string to search for.
	object Date comparison for when resulting collections were created.
	object Date comparison for when resulting collections were updated.
	object Date comparison for when resulting collections were canceled.
limit	integer Default: 10 How many orders to return.
offset	integer Default: 0 The offset in the resulting orders.
fields	string (Comma separated string) Which fields should be included in the resulting orders.
expand	string (Comma separated string) Which relations should be expanded in the resulting orders.

Responses

Response Schema: application/json

required	Array of objects (Order)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

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.customers.listOrders()
.then(({ orders, limit, offset, count }) => {
  console.log(orders);
});

Response samples

Content type

application/json

{"orders": [{"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": 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": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"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": { }
},
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"tax_rate": 0,
"discounts": [null
],
"gift_cards": [null
],
"shipping_methods": [null
],
"payments": [{ }
],
"fulfillments": [{ }
],
"returns": [{ }
],
"claims": [{ }
],
"refunds": [{ }
],
"swaps": [{ }
],
"draft_order_id": null,
"draft_order": { },
"items": [null
],
"edits": [{ }
],
"gift_card_transactions": [null
],
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"idempotency_key": "string",
"external_id": null,
"sales_channel_id": null,
"sales_channel": {"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null
},
"shipping_total": 1000,
"raw_discount_total": 800,
"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": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get 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.

Authorizations:

Cookie Session ID

Responses

Response Schema: application/json

required

Array of objects

Array

provider_id required	string The id of the Payment Provider where the payment method is saved.
data required	object The data needed for the Payment Provider to use the saved payment method.

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.customers.paymentMethods.list()
.then(({ payment_methods }) => {
  console.log(payment_methods.length);
});

Response samples

Content type

application/json

{"payment_methods": [{"provider_id": "string",
"data": { }
}
]
}

Reset Password

Resets a Customer's password using a password token created by a previous /password-token request.

Request Body schema: application/json

email required	string <email> The email of the customer.
password required	string <password> The Customer's password.
token required	string The reset password token

Responses

Response Schema: application/json

required

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": "user@example.com",
"password": "pa$$word",
"token": "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"
}
}
}

Request Password Reset

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.

Request Body schema: application/json

required

string <email>

The email of the customer.

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"email": "user@example.com"
}

Response samples

Content type

application/json

Example

Not Allowed Error

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

Gift Cards

Gift Card endpoints that allow handling gift cards in Medusa.

Get Gift Card by Code

Retrieves a Gift Card by its associated unique code.

path Parameters

code

required

string

The unique Gift Card code.

Responses

Response Schema: application/json

required

object (Gift Card)

Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.

balance required	integer Example: 10 The remaining value on the Gift Card.
code required	string Example: "3RFT-MH2C-Y4YZ-XMN4" The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card.
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.
ends_at required	string or null <date-time> The time at which the Gift Card can no longer be used.
id required	string Example: "gift_01G8XKBPBQY2R7RBET4J7E0XQZ" The gift card's ID
is_disabled required	boolean Default: false Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
order_id required	string or null Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The id of the Order that the Gift Card was purchased in.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The id of the Region in which the Gift Card is available.
tax_rate required	number or null Example: 0 The gift card's tax rate that will be applied on calculating totals
updated_at required	string <date-time> The date with timezone at which the resource was updated.
value required	integer Example: 10 The value that the Gift Card represents.
	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.
order	object or null An order object. Available if the relation `order` is expanded.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"gift_card": {"id": "gift_01G8XKBPBQY2R7RBET4J7E0XQZ",
"code": "3RFT-MH2C-Y4YZ-XMN4",
"value": 10,
"balance": 10,
"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"
}
},
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"is_disabled": false,
"ends_at": "2019-08-24T14:15:22Z",
"tax_rate": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Order Edits

Retrieve an OrderEdit

Retrieves a OrderEdit.

path Parameters

required

string

The ID of the OrderEdit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit keeps track of order items changes.

canceled_at required	string or null <date-time> The date with timezone at which the edit was cancelled.
canceled_by required	string or null The unique identifier of the user or customer who cancelled the order edit.
confirmed_by required	string or null The unique identifier of the user or customer who confirmed the order edit.
confirmed_at required	string or null <date-time> The date with timezone at which the edit was confirmed.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The unique identifier of the user or customer who created the order edit.
declined_at required	string or null <date-time> The date with timezone at which the edit was declined.
declined_by required	string or null The unique identifier of the user or customer who declined the order edit.
declined_reason required	string or null An optional note why the order edit is declined.
id required	string Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK" The order edit's ID
internal_note required	string or null Example: "Included two more items B to the order." An optional note with additional details about the order edit.
order_id required	string Example: "order_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the order that is edited
payment_collection_id required	string or null Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the payment collection
requested_at required	string or null <date-time> The date with timezone at which the edit was requested.
requested_by required	string or null The unique identifier of the user or customer who requested the order edit.
status required	string Enum: "confirmed" "declined" "requested" "created" "canceled" The status of the order edit.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
order	object or null Available if the relation `order` is expanded.
	Array of objects (Order Item Change) Available if the relation `changes` is expanded.
subtotal	integer Example: 8000 The total of subtotal
discount_total	integer Example: 800 The total of discount
shipping_total	integer Example: 800 The total of the shipping amount
gift_card_total	integer Example: 800 The total of the gift card amount
gift_card_tax_total	integer Example: 800 The total of the gift card tax amount
tax_total	integer Example: 0 The total of tax
total	integer Example: 8200 The total amount of the edited order.
difference_due	integer Example: 8200 The difference between the total amount of the order and total amount of edited order.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Payment Collection) Payment Collection

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.orderEdits.retrieve(order_edit_id)
.then(({ order_edit }) => {
  console.log(order_edit.id);
});

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"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,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Completes an OrderEdit

Completes an OrderEdit.

path Parameters

required

string

The ID of the Order Edit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit keeps track of order items changes.

canceled_at required	string or null <date-time> The date with timezone at which the edit was cancelled.
canceled_by required	string or null The unique identifier of the user or customer who cancelled the order edit.
confirmed_by required	string or null The unique identifier of the user or customer who confirmed the order edit.
confirmed_at required	string or null <date-time> The date with timezone at which the edit was confirmed.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The unique identifier of the user or customer who created the order edit.
declined_at required	string or null <date-time> The date with timezone at which the edit was declined.
declined_by required	string or null The unique identifier of the user or customer who declined the order edit.
declined_reason required	string or null An optional note why the order edit is declined.
id required	string Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK" The order edit's ID
internal_note required	string or null Example: "Included two more items B to the order." An optional note with additional details about the order edit.
order_id required	string Example: "order_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the order that is edited
payment_collection_id required	string or null Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the payment collection
requested_at required	string or null <date-time> The date with timezone at which the edit was requested.
requested_by required	string or null The unique identifier of the user or customer who requested the order edit.
status required	string Enum: "confirmed" "declined" "requested" "created" "canceled" The status of the order edit.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
order	object or null Available if the relation `order` is expanded.
	Array of objects (Order Item Change) Available if the relation `changes` is expanded.
subtotal	integer Example: 8000 The total of subtotal
discount_total	integer Example: 800 The total of discount
shipping_total	integer Example: 800 The total of the shipping amount
gift_card_total	integer Example: 800 The total of the gift card amount
gift_card_tax_total	integer Example: 800 The total of the gift card tax amount
tax_total	integer Example: 0 The total of tax
total	integer Example: 8200 The total amount of the edited order.
difference_due	integer Example: 8200 The difference between the total amount of the order and total amount of edited order.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Payment Collection) Payment Collection

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"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,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Decline an OrderEdit

Declines an OrderEdit.

path Parameters

required

string

The ID of the OrderEdit.

Request Body schema: application/json

declined_reason

string

The reason for declining the OrderEdit.

Responses

Response Schema: application/json

required

object (Order Edit)

Order edit keeps track of order items changes.

canceled_at required	string or null <date-time> The date with timezone at which the edit was cancelled.
canceled_by required	string or null The unique identifier of the user or customer who cancelled the order edit.
confirmed_by required	string or null The unique identifier of the user or customer who confirmed the order edit.
confirmed_at required	string or null <date-time> The date with timezone at which the edit was confirmed.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The unique identifier of the user or customer who created the order edit.
declined_at required	string or null <date-time> The date with timezone at which the edit was declined.
declined_by required	string or null The unique identifier of the user or customer who declined the order edit.
declined_reason required	string or null An optional note why the order edit is declined.
id required	string Example: "oe_01G8TJSYT9M6AVS5N4EMNFS1EK" The order edit's ID
internal_note required	string or null Example: "Included two more items B to the order." An optional note with additional details about the order edit.
order_id required	string Example: "order_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the order that is edited
payment_collection_id required	string or null Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the payment collection
requested_at required	string or null <date-time> The date with timezone at which the edit was requested.
requested_by required	string or null The unique identifier of the user or customer who requested the order edit.
status required	string Enum: "confirmed" "declined" "requested" "created" "canceled" The status of the order edit.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
order	object or null Available if the relation `order` is expanded.
	Array of objects (Order Item Change) Available if the relation `changes` is expanded.
subtotal	integer Example: 8000 The total of subtotal
discount_total	integer Example: 800 The total of discount
shipping_total	integer Example: 800 The total of the shipping amount
gift_card_total	integer Example: 800 The total of the gift card amount
gift_card_tax_total	integer Example: 800 The total of the gift card tax amount
tax_total	integer Example: 0 The total of tax
total	integer Example: 8200 The total amount of the edited order.
difference_due	integer Example: 8200 The difference between the total amount of the order and total amount of edited order.
	Array of objects (Line Item) Available if the relation `items` is expanded.
	object (Payment Collection) Payment Collection

Request samples

Payload
JS Client
cURL

Content type

application/json

{"declined_reason": "string"
}

Response samples

Content type

application/json

{"order_edit": {"id": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order_id": "order_01G2SG30J8C85S4A5CHM2S1NS2",
"order": { },
"changes": [{"id": null,
"type": null,
"order_edit_id": null,
"order_edit": { },
"original_line_item_id": null,
"original_line_item": null,
"line_item_id": null,
"line_item": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"internal_note": "Included two more items B to the order.",
"created_by": "string",
"requested_by": "string",
"requested_at": "2019-08-24T14:15:22Z",
"confirmed_by": "string",
"confirmed_at": "2019-08-24T14:15:22Z",
"declined_by": "string",
"declined_at": "2019-08-24T14:15:22Z",
"declined_reason": "string",
"canceled_by": "string",
"canceled_at": "2019-08-24T14:15:22Z",
"subtotal": 8000,
"discount_total": 800,
"shipping_total": 800,
"gift_card_total": 800,
"gift_card_tax_total": 800,
"tax_total": 0,
"total": 8200,
"difference_due": 8200,
"status": "confirmed",
"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,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"payment_collection_id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"currency_code": "usd",
"currency": {"code": null,
"symbol": null,
"symbol_native": null,
"name": null,
"includes_tax": null
},
"payment_sessions": [null
],
"payments": [null
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Orders

Order endpoints that allow handling orders in Medusa.

Look Up an Order

Look up an order using filters.

query Parameters

display_id required	number The display id given to the Order.
email required	string <email> The email associated with this order.
fields	string (Comma separated) Which fields should be included in the result.
expand	string (Comma separated) Which fields should be expanded in the result.
	object The shipping address associated with this order.

Responses

Response Schema: application/json

required

object (Order)

Represents an order

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the billing address associated with the order
canceled_at required	string or null <date-time> The date the order was canceled on.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The ID of the cart associated with the order
created_at required	string <date-time> The date with timezone at which the resource was created.
currency_code required	string Example: "usd" The 3 character currency code that is used in the order See a list of codes.
customer_id required	string Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the customer associated with the order
draft_order_id required	string or null Example: null The ID of the draft order this order is associated with.
display_id required	integer Example: 2 The order's display ID
email required	string <email> The email associated with the order
external_id required	string or null Example: null The ID of an external order.
fulfillment_status required	string Default: "not_fulfilled" Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action" The order's fulfillment status
id required	string Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The order's ID
idempotency_key required	string or null Randomly generated key used to continue the processing of the order 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
no_notification required	boolean or null Example: false Flag for describing whether or not notifications related to this should be send.
payment_status required	string Default: "not_paid" Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refunded" "canceled" "requires_action" The order's payment status
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the shipping address associated with the order
status required	string Default: "pending" Enum: "pending" "completed" "archived" "canceled" "requires_action" The order's status
tax_rate required	number or null Example: 0 The order's tax rate
updated_at required	string <date-time> The date with timezone at which the resource was updated.
cart	object or null A cart object. Available if the relation `cart` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
	object (Address) An address.
	object (Address) An address.
	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.
	object (Currency) Currency
	Array of objects (Discount) The discounts used in the order. Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) The gift cards used in the order. Available if the relation `gift_cards` is expanded.
	Array of objects (Shipping Method) The shipping methods used in the order. Available if the relation `shipping_methods` is expanded.
payments	Array of objects The payments used in the order. Available if the relation `payments` is expanded.
fulfillments	Array of objects The fulfillments used in the order. Available if the relation `fulfillments` is expanded.
returns	Array of objects The returns associated with the order. Available if the relation `returns` is expanded.
claims	Array of objects The claims associated with the order. Available if the relation `claims` is expanded.
refunds	Array of objects The refunds associated with the order. Available if the relation `refunds` is expanded.
swaps	Array of objects The swaps associated with the order. Available if the relation `swaps` is expanded.
draft_order	object or null A draft order object. Available if the relation `draft_order` is expanded.
	Array of objects (Line Item) The line items that belong to the order. Available if the relation `items` is expanded.
edits	Array of objects Order edits done on the order. Available if the relation `edits` is expanded.
	Array of objects (Gift Card Transaction) The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded.
sales_channel_id	string or null Example: null The ID of the sales channel this order is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order is returned.
total	integer Example: 8200 The total amount of the order
subtotal	integer Example: 8000 The subtotal of the order
paid_total	integer Example: 8000 The total amount paid
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
	Array of objects (Line Item) The items that are returnable as part of the order, order swaps or order claims

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.orders.lookupOrder({
  display_id: 1,
  email: 'user@example.com'
})
.then(({ order }) => {
  console.log(order.id);
});

Response samples

Content type

application/json

{"order": {"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,
"raw_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,
"raw_discount_total": 800,
"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,
"raw_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"
}
}
}

Claim an Order

Sends an email to emails registered to orders provided with link to transfer order ownership

Authorizations:

NoneCookie Session ID

Request Body schema: application/json

order_ids

required

Array of strings

The ids of the orders to claim

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_ids": ["string"
]
}

Response samples

Content type

application/json

Example

Not Allowed Error

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

Get by Cart ID

Retrieves an Order by the id of the Cart that was used to create the Order.

path Parameters

cart_id

required

string

The ID of Cart.

Responses

Response Schema: application/json

required

object (Order)

Represents an order

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the billing address associated with the order
canceled_at required	string or null <date-time> The date the order was canceled on.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The ID of the cart associated with the order
created_at required	string <date-time> The date with timezone at which the resource was created.
currency_code required	string Example: "usd" The 3 character currency code that is used in the order See a list of codes.
customer_id required	string Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the customer associated with the order
draft_order_id required	string or null Example: null The ID of the draft order this order is associated with.
display_id required	integer Example: 2 The order's display ID
email required	string <email> The email associated with the order
external_id required	string or null Example: null The ID of an external order.
fulfillment_status required	string Default: "not_fulfilled" Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action" The order's fulfillment status
id required	string Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The order's ID
idempotency_key required	string or null Randomly generated key used to continue the processing of the order 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
no_notification required	boolean or null Example: false Flag for describing whether or not notifications related to this should be send.
payment_status required	string Default: "not_paid" Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refunded" "canceled" "requires_action" The order's payment status
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the shipping address associated with the order
status required	string Default: "pending" Enum: "pending" "completed" "archived" "canceled" "requires_action" The order's status
tax_rate required	number or null Example: 0 The order's tax rate
updated_at required	string <date-time> The date with timezone at which the resource was updated.
cart	object or null A cart object. Available if the relation `cart` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
	object (Address) An address.
	object (Address) An address.
	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.
	object (Currency) Currency
	Array of objects (Discount) The discounts used in the order. Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) The gift cards used in the order. Available if the relation `gift_cards` is expanded.
	Array of objects (Shipping Method) The shipping methods used in the order. Available if the relation `shipping_methods` is expanded.
payments	Array of objects The payments used in the order. Available if the relation `payments` is expanded.
fulfillments	Array of objects The fulfillments used in the order. Available if the relation `fulfillments` is expanded.
returns	Array of objects The returns associated with the order. Available if the relation `returns` is expanded.
claims	Array of objects The claims associated with the order. Available if the relation `claims` is expanded.
refunds	Array of objects The refunds associated with the order. Available if the relation `refunds` is expanded.
swaps	Array of objects The swaps associated with the order. Available if the relation `swaps` is expanded.
draft_order	object or null A draft order object. Available if the relation `draft_order` is expanded.
	Array of objects (Line Item) The line items that belong to the order. Available if the relation `items` is expanded.
edits	Array of objects Order edits done on the order. Available if the relation `edits` is expanded.
	Array of objects (Gift Card Transaction) The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded.
sales_channel_id	string or null Example: null The ID of the sales channel this order is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order is returned.
total	integer Example: 8200 The total amount of the order
subtotal	integer Example: 8000 The subtotal of the order
paid_total	integer Example: 8000 The total amount paid
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
	Array of objects (Line Item) The items that are returnable as part of the order, order swaps or order claims

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"order": {"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,
"raw_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,
"raw_discount_total": 800,
"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,
"raw_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"
}
}
}

Verify an Order Claim

Verifies the claim order token provided to the customer upon request of order ownership

Authorizations:

NoneCookie Session ID

Request Body schema: application/json

token

required

string

The invite token provided by the admin.

Responses

Request samples

Payload
JS Client
cURL

Content type

application/json

{"token": "string"
}

Response samples

Content type

application/json

Example

Not Allowed Error

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

Get an Order

Retrieves an Order

path Parameters

required

string

The id of the Order.

query Parameters

fields	string (Comma separated) Which fields should be included in the result.
expand	string (Comma separated) Which fields should be expanded in the result.

Responses

Response Schema: application/json

required

object (Order)

Represents an order

billing_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the billing address associated with the order
canceled_at required	string or null <date-time> The date the order was canceled on.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The ID of the cart associated with the order
created_at required	string <date-time> The date with timezone at which the resource was created.
currency_code required	string Example: "usd" The 3 character currency code that is used in the order See a list of codes.
customer_id required	string Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2" The ID of the customer associated with the order
draft_order_id required	string or null Example: null The ID of the draft order this order is associated with.
display_id required	integer Example: 2 The order's display ID
email required	string <email> The email associated with the order
external_id required	string or null Example: null The ID of an external order.
fulfillment_status required	string Default: "not_fulfilled" Enum: "not_fulfilled" "partially_fulfilled" "fulfilled" "partially_shipped" "shipped" "partially_returned" "returned" "canceled" "requires_action" The order's fulfillment status
id required	string Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The order's ID
idempotency_key required	string or null Randomly generated key used to continue the processing of the order 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
no_notification required	boolean or null Example: false Flag for describing whether or not notifications related to this should be send.
payment_status required	string Default: "not_paid" Enum: "not_paid" "awaiting" "captured" "partially_refunded" "refunded" "canceled" "requires_action" The order's payment status
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The ID of the shipping address associated with the order
status required	string Default: "pending" Enum: "pending" "completed" "archived" "canceled" "requires_action" The order's status
tax_rate required	number or null Example: 0 The order's tax rate
updated_at required	string <date-time> The date with timezone at which the resource was updated.
cart	object or null A cart object. Available if the relation `cart` is expanded.
customer	object or null A customer object. Available if the relation `customer` is expanded.
	object (Address) An address.
	object (Address) An address.
	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.
	object (Currency) Currency
	Array of objects (Discount) The discounts used in the order. Available if the relation `discounts` is expanded.
	Array of objects (Gift Card) The gift cards used in the order. Available if the relation `gift_cards` is expanded.
	Array of objects (Shipping Method) The shipping methods used in the order. Available if the relation `shipping_methods` is expanded.
payments	Array of objects The payments used in the order. Available if the relation `payments` is expanded.
fulfillments	Array of objects The fulfillments used in the order. Available if the relation `fulfillments` is expanded.
returns	Array of objects The returns associated with the order. Available if the relation `returns` is expanded.
claims	Array of objects The claims associated with the order. Available if the relation `claims` is expanded.
refunds	Array of objects The refunds associated with the order. Available if the relation `refunds` is expanded.
swaps	Array of objects The swaps associated with the order. Available if the relation `swaps` is expanded.
draft_order	object or null A draft order object. Available if the relation `draft_order` is expanded.
	Array of objects (Line Item) The line items that belong to the order. Available if the relation `items` is expanded.
edits	Array of objects Order edits done on the order. Available if the relation `edits` is expanded.
	Array of objects (Gift Card Transaction) The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded.
sales_channel_id	string or null Example: null The ID of the sales channel this order is associated with.
	object (Sales Channel) A Sales Channel
shipping_total	integer Example: 1000 The total of shipping
raw_discount_total	integer Example: 800 The total of discount
discount_total	integer Example: 800 The total of discount rounded
tax_total	integer Example: 0 The total of tax
refunded_total	integer Example: 0 The total amount refunded if the order is returned.
total	integer Example: 8200 The total amount of the order
subtotal	integer Example: 8000 The subtotal of the order
paid_total	integer Example: 8000 The total amount paid
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
	Array of objects (Line Item) The items that are returnable as part of the order, order swaps or order claims

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.orders.retrieve(order_id)
.then(({ order }) => {
  console.log(order.id);
});

Response samples

Content type

application/json

{"order": {"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,
"raw_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,
"raw_discount_total": 800,
"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,
"raw_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"
}
}
}

Payment Collections

Get a PaymentCollection

Get a Payment Collection

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the PaymentCollection.

query Parameters

expand	string Comma separated list of relations to include in the results.
fields	string Comma separated list of fields to include in the results.

Responses

Response Schema: application/json

required

object (Payment Collection)

Payment Collection

amount required	integer Amount of the payment collection.
authorized_amount required	integer or null Authorized amount of the payment collection.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The ID of the user that created the payment collection.
currency_code required	string Example: "usd" The 3 character ISO code for the currency. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
description required	string or null Description of the payment collection
id required	string Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The payment collection's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
status required	string Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled" The type of the payment collection
type required	string Value: "order_edit" The type of the payment collection
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	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.
	object (Currency) Currency
	Array of objects (Payment Session) Available if the relation `payment_sessions` is expanded.
	Array of objects (Payment) Available if the relation `payments` 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 in or use api token
medusa.paymentCollections.retrieve(paymentCollectionId)
  .then(({ payment_collection }) => {
    console.log(payment_collection.id)
  })

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"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
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Manage a Payment Session

Manages Payment Sessions from Payment Collections.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the Payment Collection.

Request Body schema: application/json

provider_id

required

string

The ID of the Payment Provider.

Responses

Response Schema: application/json

required

object (Payment Collection)

Payment Collection

amount required	integer Amount of the payment collection.
authorized_amount required	integer or null Authorized amount of the payment collection.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The ID of the user that created the payment collection.
currency_code required	string Example: "usd" The 3 character ISO code for the currency. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
description required	string or null Description of the payment collection
id required	string Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The payment collection's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
status required	string Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled" The type of the payment collection
type required	string Value: "order_edit" The type of the payment collection
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	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.
	object (Currency) Currency
	Array of objects (Payment Session) Available if the relation `payment_sessions` is expanded.
	Array of objects (Payment) Available if the relation `payments` is expanded.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"provider_id": "string"
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"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
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Manage Payment Sessions

Manages Multiple Payment Sessions from Payment Collections.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the Payment Collections.

Request Body schema: application/json

required

Array of objects

An array of payment sessions related to the Payment Collection. If the session_id is not provided, existing sessions not present will be deleted and the provided ones will be created.

Array

provider_id required	string The ID of the Payment Provider.
amount required	integer The amount .
session_id	string The ID of the Payment Session to be updated.

Responses

Response Schema: application/json

required

object (Payment Collection)

Payment Collection

amount required	integer Amount of the payment collection.
authorized_amount required	integer or null Authorized amount of the payment collection.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The ID of the user that created the payment collection.
currency_code required	string Example: "usd" The 3 character ISO code for the currency. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
description required	string or null Description of the payment collection
id required	string Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The payment collection's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
status required	string Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled" The type of the payment collection
type required	string Value: "order_edit" The type of the payment collection
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	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.
	object (Currency) Currency
	Array of objects (Payment Session) Available if the relation `payment_sessions` is expanded.
	Array of objects (Payment) Available if the relation `payments` is expanded.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"sessions": [{"provider_id": "string",
"amount": 0,
"session_id": "string"
}
]
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"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
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Authorize PaymentSessions

Authorizes Payment Sessions of a Payment Collection.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the Payment Collections.

Request Body schema: application/json

session_ids

required

Array of strings

List of Payment Session IDs to authorize.

Responses

Response Schema: application/json

required

object (Payment Collection)

Payment Collection

amount required	integer Amount of the payment collection.
authorized_amount required	integer or null Authorized amount of the payment collection.
created_at required	string <date-time> The date with timezone at which the resource was created.
created_by required	string The ID of the user that created the payment collection.
currency_code required	string Example: "usd" The 3 character ISO code for the currency. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
description required	string or null Description of the payment collection
id required	string Example: "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" The payment collection's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
status required	string Enum: "not_paid" "awaiting" "authorized" "partially_authorized" "canceled" The type of the payment collection
type required	string Value: "order_edit" The type of the payment collection
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	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.
	object (Currency) Currency
	Array of objects (Payment Session) Available if the relation `payment_sessions` is expanded.
	Array of objects (Payment) Available if the relation `payments` is expanded.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"session_ids": ["string"
]
}

Response samples

Content type

application/json

{"payment_collection": {"id": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK",
"type": "order_edit",
"status": "not_paid",
"description": "string",
"amount": 0,
"authorized_amount": 0,
"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
},
"payment_sessions": [{"id": null,
"cart_id": null,
"cart": null,
"provider_id": null,
"is_selected": null,
"is_initiated": null,
"status": null,
"data": { },
"idempotency_key": null,
"amount": null,
"payment_authorized_at": null,
"created_at": null,
"updated_at": null
}
],
"payments": [{"id": null,
"swap_id": null,
"swap": { },
"cart_id": null,
"cart": { },
"order_id": null,
"order": { },
"amount": null,
"currency_code": null,
"currency": null,
"amount_refunded": null,
"provider_id": null,
"data": { },
"captured_at": null,
"canceled_at": null,
"idempotency_key": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Refresh a Payment Session

Refreshes a Payment Session to ensure that it is in sync with the Payment Collection.

path Parameters

id required	string The id of the PaymentCollection.
session_id required	string The id of the Payment Session to be refreshed.

Responses

Response Schema: application/json

required

object (Payment Session)

Payment Sessions are created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, who is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for capture/refunds/etc.

amount required	integer or null Example: 100 The amount that the Payment Session has been authorized for.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The id of the Cart that the Payment Session is created for.
created_at required	string <date-time> The date with timezone at which the resource was created.
data required	object Example: {} The data required for the Payment Provider to identify, modify and process the Payment Session. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.
id required	string Example: "ps_01G901XNSRM2YS3ASN9H5KG3FZ" The payment session's ID
is_initiated required	boolean Default: false Example: true A flag to indicate if a communication with the third party provider has been initiated.
is_selected required	boolean or null Example: true A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase.
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.
payment_authorized_at required	string or null <date-time> The date with timezone at which the Payment Session was authorized.
provider_id required	string Example: "manual" The id of the Payment Provider that is responsible for the Payment Session
status required	string Enum: "authorized" "pending" "requires_more" "error" "canceled" Example: "pending" Indicates the status of the Payment Session. Will default to `pending`, and will eventually become `authorized`. Payment Sessions may have the status of `requires_more` to indicate that further actions are to be completed by the Customer.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Cart) Represents a user cart

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.paymentCollections.refreshPaymentSession(payment_collection_id, session_id)
.then(({ payment_session }) => {
  console.log(payment_session.id);
});

Response samples

Content type

application/json

{"payment_session": {"id": "ps_01G901XNSRM2YS3ASN9H5KG3FZ",
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"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": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"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": { }
},
"items": [null
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"discounts": [null
],
"gift_cards": [null
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [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": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null
},
"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,
"raw_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
},
"provider_id": "manual",
"is_selected": true,
"is_initiated": true,
"status": "pending",
"data": { },
"idempotency_key": "string",
"amount": 100,
"payment_authorized_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Authorize Payment Session

Authorizes a Payment Session of a Payment Collection.

Authorizations:

NoneCookie Session ID

path Parameters

id required	string The ID of the Payment Collections.
session_id required	string The ID of the Payment Session.

Responses

Response Schema: application/json

required

object (Payment Session)

amount required	integer or null Example: 100 The amount that the Payment Session has been authorized for.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The id of the Cart that the Payment Session is created for.
created_at required	string <date-time> The date with timezone at which the resource was created.
data required	object Example: {} The data required for the Payment Provider to identify, modify and process the Payment Session. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.
id required	string Example: "ps_01G901XNSRM2YS3ASN9H5KG3FZ" The payment session's ID
is_initiated required	boolean Default: false Example: true A flag to indicate if a communication with the third party provider has been initiated.
is_selected required	boolean or null Example: true A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase.
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.
payment_authorized_at required	string or null <date-time> The date with timezone at which the Payment Session was authorized.
provider_id required	string Example: "manual" The id of the Payment Provider that is responsible for the Payment Session
status required	string Enum: "authorized" "pending" "requires_more" "error" "canceled" Example: "pending" Indicates the status of the Payment Session. Will default to `pending`, and will eventually become `authorized`. Payment Sessions may have the status of `requires_more` to indicate that further actions are to be completed by the Customer.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Cart) Represents a user cart

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 in or use api token
medusa.paymentCollections.authorize(payment_id, session_id)
.then(({ payment_collection }) => {
  console.log(payment_collection.id);
});

Response samples

Content type

application/json

{"payment_session": {"id": "ps_01G901XNSRM2YS3ASN9H5KG3FZ",
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": {"id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"email": "user@example.com",
"billing_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"billing_address": {"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": { }
},
"shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
"shipping_address": {"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": { }
},
"items": [null
],
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": {"id": null,
"name": null,
"currency_code": null,
"currency": null,
"tax_rate": null,
"tax_rates": [ ],
"tax_code": null,
"gift_cards_taxable": null,
"automatic_taxes": null,
"countries": [ ],
"tax_provider_id": null,
"tax_provider": null,
"payment_providers": [ ],
"fulfillment_providers": [ ],
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"discounts": [null
],
"gift_cards": [null
],
"customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
"customer": { },
"payment_session": { },
"payment_sessions": [{ }
],
"payment_id": "pay_01G8ZCC5W42ZNY842124G7P5R9",
"payment": { },
"shipping_methods": [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": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null
},
"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,
"raw_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
},
"provider_id": "manual",
"is_selected": true,
"is_initiated": true,
"status": "pending",
"data": { },
"idempotency_key": "string",
"amount": 100,
"payment_authorized_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Product Categories

List Product Categories

Retrieve a list of product categories.

Authorizations:

NoneCookie Session ID

query Parameters

q	string Query used for searching product category names or handles.
handle	string Query used for searching product category by handle.
parent_category_id	string Returns categories scoped by parent
include_descendants_tree	boolean Include all nested descendants of category
offset	integer Default: 0 How many product categories to skip in the result.
limit	integer Default: 100 Limit the number of product categories returned.

Responses

Response Schema: application/json

required	Array of objects (ProductCategory)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.productCategories.list()
.then(({ product_categories, limit, offset, count }) => {
  console.log(product_categories.length);
});

Response samples

Content type

application/json

{"product_categories": [{"id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
"name": "Regular Fit",
"handle": "regular-fit",
"mpath": "pcat_id1.pcat_id2.pcat_id3",
"is_internal": false,
"is_active": false,
"rank": 0,
"category_children": [{ }
],
"parent_category_id": null,
"parent_category": { },
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Get a Product Category

Retrieves a Product Category.

Authorizations:

NoneCookie Session ID

path Parameters

required

string

The ID of the Product Category

query Parameters

expand	string (Comma separated) Which fields should be expanded in each product category.
fields	string (Comma separated) Which fields should be retrieved in each product category.

Responses

Response Schema: application/json

required

object (ProductCategory)

Represents a product category

category_children required	Array of objects Available if the relation `category_children` are expanded.
created_at required	string <date-time> The date with timezone at which the resource was created.
handle required	string Example: "regular-fit" A unique string that identifies the Product Category - can for example be used in slug structures.
id required	string Example: "pcat_01G2SG30J8C85S4A5CHM2S1NS2" The product category's ID
is_active required	boolean Default: false A flag to make product category visible/hidden in the store front
is_internal required	boolean Default: false A flag to make product category an internal category for admins
mpath required	string or null Example: "pcat_id1.pcat_id2.pcat_id3" A string for Materialized Paths - used for finding ancestors and descendents
name required	string Example: "Regular Fit" The product category's name
parent_category_id required	string or null Default: null The ID of the parent category.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
rank	integer Default: 0 An integer that depicts the rank of category in a tree node
parent_category	object or null A product category object. Available if the relation `parent_category` is expanded.
products	Array of objects Products associated with category. Available if the relation `products` 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 in or use api token
medusa.productCategories.retrieve(product_category_id)
  .then(({ product_category }) => {
    console.log(product_category.id);
  });

Response samples

Content type

application/json

{"product_category": {"id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
"name": "Regular Fit",
"handle": "regular-fit",
"mpath": "pcat_id1.pcat_id2.pcat_id3",
"is_internal": false,
"is_active": false,
"rank": 0,
"category_children": [{ }
],
"parent_category_id": null,
"parent_category": { },
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}

Product Tags

List Product Tags

Retrieve a list of Product Tags.

query Parameters

limit	integer Default: 20 The number of types to return.
offset	integer Default: 0 The number of items to skip before the results.
order	string The field to sort items by.
discount_condition_id	string The discount condition id on which to filter the product tags.
value	Array of strings The tag values to search for
id	Array of strings The tag IDs to search for
q	string A query string to search values for
	object Date comparison for when resulting product tags were created.
	object Date comparison for when resulting product tags were updated.

Responses

Response Schema: application/json

required	Array of objects (Product Tag)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.productTags.list()
.then(({ product_tags }) => {
  console.log(product_tags.length);
});

Response samples

Content type

application/json

{"product_tags": [{"id": "ptag_01G8K2MTMG9168F2B70S1TAVK3",
"value": "Pants",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Product Types

List Product Types

Retrieve a list of Product Types.

Authorizations:

NoneCookie Session ID

query Parameters

limit	integer Default: 20 The number of types to return.
offset	integer Default: 0 The number of items to skip before the results.
order	string The field to sort items by.
discount_condition_id	string The discount condition id on which to filter the product types.
value	Array of strings The type values to search for
id	Array of strings The type IDs to search for
q	string A query string to search values for
	object Date comparison for when resulting product types were created.
	object Date comparison for when resulting product types were updated.

Responses

Response Schema: application/json

required	Array of objects (Product Type)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

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 in or use api token
medusa.productTypes.list()
.then(({ product_types }) => {
  console.log(product_types.length);
});

Response samples

Content type

application/json

{"product_types": [{"id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"value": "Clothing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Product Variants

Product Variant endpoints that allow handling product variants in Medusa.

Products

Product endpoints that allow handling products in Medusa.

List Products

Retrieves a list of Products.

query Parameters

q	string Query used for searching products by title, description, variant's title, variant's sku, and collection's title
	string or Array of strings product IDs to search for.
sales_channel_id	Array of strings an array of sales channel IDs to filter the retrieved products by.
collection_id	Array of strings Collection IDs to search for
type_id	Array of strings Type IDs to search for
tags	Array of strings Tag IDs to search for
title	string title to search for.
description	string description to search for.
handle	string handle to search for.
is_giftcard	boolean Search for giftcards using is_giftcard=true.
	object Date comparison for when resulting products were created.
	object Date comparison for when resulting products were updated.
category_id	Array of strings Category ids to filter by.
include_category_children	boolean Include category children when filtering by category_id.
offset	integer Default: 0 How many products to skip in the result.
limit	integer Default: 100 Limit the number of products returned.
expand	string (Comma separated) Which fields should be expanded in each product of the result.
fields	string (Comma separated) Which fields should be included in each product of the result.
order	string the field used to order the products.
cart_id	string The id of the Cart to set prices based on.
region_id	string The id of the Region to set prices based on.
currency_code	string The currency code to use for price selection.

Responses

Response Schema: application/json

required	Array of objects (Priced Product)
count required	integer The total number of items available
offset required	integer The number of items skipped before these items
limit required	integer The number of items per page

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.list()
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
});

Response samples

Content type

application/json

{"products": [{"id": "prod_01G1G5V2MBA328390B5AXJ610F",
"title": "Medusa Coffee Mug",
"subtitle": "string",
"description": "Every programmer's best friend.",
"handle": "coffee-mug",
"is_giftcard": false,
"status": "draft",
"images": [null
],
"thumbnail": "http://example.com",
"options": [null
],
"variants": [null
],
"categories": [null
],
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"collection": {"id": null,
"title": null,
"handle": null,
"products": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"type": {"id": null,
"value": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"tags": [null
],
"discountable": true,
"external_id": null,
"sales_channels": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
],
"count": 0,
"offset": 0,
"limit": 0
}

Search Products

Run a search query on products using the search engine installed on Medusa

query Parameters

q required	string The query to run the search with.
offset	integer How many products to skip in the result.
limit	integer Limit the number of products returned.

Responses

Response Schema: application/json

hits

required

Array of arrays

Array of results. The format of the items depends on the search engine installed on the server.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.search({
  q: 'Shirt'
})
.then(({ hits }) => {
  console.log(hits.length);
});

Response samples

Content type

application/json

{"hits": [ ]
}

Get a Product

Retrieves a Product.

path Parameters

required

string

The id of the Product.

query Parameters

sales_channel_id	string The sales channel used when fetching the product.
cart_id	string The ID of the customer's cart.
region_id	string The ID of the region the customer is using. This is helpful to ensure correct prices are retrieved for a region.
fields	string (Comma separated) Which fields should be included in the result.
expand	string (Comma separated) Which fields should be expanded in each product of the result.
currency_code	string The 3 character ISO currency code to set prices based on. This is helpful to ensure correct prices are retrieved for a currency. See a list of codes.

Responses

Response Schema: application/json

required

object (Priced 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.

collection_id required	string or null Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG" The Product Collection that the Product belongs to
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.
description required	string or null Example: "Every programmer's best friend." A short description of the Product.
discountable required	boolean Default: true Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to `false`.
external_id required	string or null Example: null The external ID of the product
handle required	string or null Example: "coffee-mug" A unique identifier for the Product (e.g. for slug structure).
height required	number or null Example: null The height of the Product Variant. May be used in shipping rate calculations.
hs_code required	string or null Example: null The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
id required	string Example: "prod_01G1G5V2MBA328390B5AXJ610F" The product's ID
is_giftcard required	boolean Default: false Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.
length required	number or null Example: null The length of the Product Variant. May be used in shipping rate calculations.
material required	string or null Example: null The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
mid_code required	string or null Example: null The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
origin_country required	string or null Example: null The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
profile_id required	string Example: "sp_01G1G5V239ENSZ5MV4JAR737BM" The ID of the Shipping Profile that the Product belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.
status required	string Default: "draft" Enum: "draft" "proposed" "published" "rejected" The status of the product
subtitle required	string or null An optional subtitle that can be used to further specify the Product.
type_id required	string or null Example: "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A" The Product type that the Product belongs to
thumbnail required	string or null <uri> A URL to an image file that can be used to identify the Product.
title required	string Example: "Medusa Coffee Mug" A title that can be displayed for easy identification of the Product.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
weight required	number or null Example: null The weight of the Product Variant. May be used in shipping rate calculations.
width required	number or null Example: null The width of the Product Variant. May be used in shipping rate calculations.
	Array of objects (Image) Images of the Product. Available if the relation `images` is expanded.
	Array of objects (Product Option) The Product Options that are defined for the Product. Product Variants of the Product will have a unique combination of Product Option Values. Available if the relation `options` is expanded.
	Array of objects (Product Variant) The Product Variants that belong to the Product. Each will have a unique combination of Product Option Values. Available if the relation `variants` is expanded.
	Array of objects (ProductCategory) The product's associated categories. Available if the relation `categories` are expanded.
	object (Shipping Profile) Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.
	object (Product Collection) Product Collections represents a group of Products that are related.
	object (Product Type) Product Type can be added to Products for filtering and reporting purposes.
	Array of objects (Product Tag) The Product Tags assigned to the Product. Available if the relation `tags` is expanded.
	Array of objects (Sales Channel) The sales channels the product is associated with. Available if the relation `sales_channels` is expanded.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.retrieve(product_id)
.then(({ product }) => {
  console.log(product.id);
});

Response samples

Content type

application/json

{"product": {"id": "prod_01G1G5V2MBA328390B5AXJ610F",
"title": "Medusa Coffee Mug",
"subtitle": "string",
"description": "Every programmer's best friend.",
"handle": "coffee-mug",
"is_giftcard": false,
"status": "draft",
"images": [{"id": null,
"url": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"thumbnail": "http://example.com",
"options": [{"id": null,
"title": null,
"values": [ ],
"product_id": null,
"product": { },
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"variants": [{"id": null,
"title": null,
"product_id": null,
"product": { },
"prices": [ ],
"sku": null,
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": null,
"inventory_quantity": null,
"allow_backorder": null,
"manage_inventory": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"weight": null,
"length": null,
"height": null,
"width": null,
"options": [ ],
"inventory_items": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { },
"purchasable": null,
"original_price": null,
"calculated_price": null,
"original_price_incl_tax": null,
"calculated_price_incl_tax": null,
"original_tax": null,
"calculated_tax": null,
"tax_rates": [ ]
}
],
"categories": [{"id": null,
"name": null,
"handle": null,
"mpath": null,
"is_internal": null,
"is_active": null,
"rank": null,
"category_children": [ ],
"parent_category_id": null,
"parent_category": { },
"products": [ ],
"created_at": null,
"updated_at": null
}
],
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"name": "Default Shipping Profile",
"type": "default",
"products": [{ }
],
"shipping_options": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"weight": null,
"length": null,
"height": null,
"width": null,
"hs_code": null,
"origin_country": null,
"mid_code": null,
"material": null,
"collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"collection": {"id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
"title": "Summer Collection",
"handle": "summer-collection",
"products": [{ }
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"type": {"id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
"value": "Clothing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
},
"tags": [{"id": null,
"value": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"discountable": true,
"external_id": null,
"sales_channels": [{"id": null,
"name": null,
"description": null,
"is_disabled": null,
"locations": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Regions

Region endpoints that allow handling regions in Medusa.

List Regions

Retrieves a list of Regions.

query Parameters

offset	integer Default: 0 How many regions to skip in the result.
limit	integer Default: 100 Limit the number of regions returned.
	object Date comparison for when resulting regions were created.
	object Date comparison for when resulting regions were updated.

Responses

Response Schema: application/json

required

Array of objects (Region)

Array

automatic_taxes required	boolean Default: true Whether taxes should be automated in this region.
created_at required	string <date-time> The date with timezone at which the resource was created.
currency_code required	string Example: "usd" The 3 character currency code that the Region uses. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
gift_cards_taxable required	boolean Default: true Whether the gift cards are taxable or not in this region.
id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
name required	string Example: "EU" The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.
tax_code required	string or null Example: null The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.
tax_provider_id required	string or null Example: null The ID of the tax provider used in this region
tax_rate required	number Example: 0 The tax rate that should be charged on purchases in the Region.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Currency) Currency
	Array of objects (Tax Rate) The tax rates that are included in the Region. Available if the relation `tax_rates` is expanded.
	Array of objects (Country) The countries that are included in the Region. Available if the relation `countries` is expanded.
	object (Tax Provider) The tax service used to calculate taxes
	Array of objects (Payment Provider) The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded.
	Array of objects (Fulfillment Provider) The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `fulfillment_providers` is expanded.
includes_tax	boolean Default: false [EXPERIMENTAL] Does the prices for the region include tax

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.regions.list()
.then(({ regions }) => {
  console.log(regions.length);
});

Response samples

Content type

application/json

{"regions": [{"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"
}
}
]
}

Get a Region

Retrieves a Region.

path Parameters

required

string

The id of the Region.

Responses

Response Schema: application/json

required

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.

automatic_taxes required	boolean Default: true Whether taxes should be automated in this region.
created_at required	string <date-time> The date with timezone at which the resource was created.
currency_code required	string Example: "usd" The 3 character currency code that the Region uses. See a list of codes.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
gift_cards_taxable required	boolean Default: true Whether the gift cards are taxable or not in this region.
id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
name required	string Example: "EU" The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.
tax_code required	string or null Example: null The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.
tax_provider_id required	string or null Example: null The ID of the tax provider used in this region
tax_rate required	number Example: 0 The tax rate that should be charged on purchases in the Region.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	object (Currency) Currency
	Array of objects (Tax Rate) The tax rates that are included in the Region. Available if the relation `tax_rates` is expanded.
	Array of objects (Country) The countries that are included in the Region. Available if the relation `countries` is expanded.
	object (Tax Provider) The tax service used to calculate taxes
	Array of objects (Payment Provider) The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded.
	Array of objects (Fulfillment Provider) The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `fulfillment_providers` is expanded.
includes_tax	boolean Default: false [EXPERIMENTAL] Does the prices for the region include tax

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.regions.retrieve(region_id)
.then(({ region }) => {
  console.log(region.id);
});

Response samples

Content type

application/json

{"region": {"id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"name": "EU",
"currency_code": "usd",
"currency": {"code": "usd",
"symbol": "$",
"symbol_native": "$",
"name": "US Dollar",
"includes_tax": false
},
"tax_rate": 0,
"tax_rates": [{"id": null,
"rate": null,
"code": null,
"name": null,
"region_id": null,
"region": { },
"products": [ ],
"product_types": [ ],
"shipping_options": [ ],
"product_count": null,
"product_type_count": null,
"shipping_option_count": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"tax_code": null,
"gift_cards_taxable": true,
"automatic_taxes": true,
"countries": [{"id": null,
"iso_2": null,
"iso_3": null,
"num_code": null,
"name": null,
"display_name": null,
"region_id": null,
"region": { }
}
],
"tax_provider_id": null,
"tax_provider": {"id": "manual",
"is_installed": true
},
"payment_providers": [{"id": null,
"is_installed": null
}
],
"fulfillment_providers": [{"id": null,
"is_installed": 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"
}
}
}

Return Reasons

Return Reason endpoints that allow handling return reasons in Medusa.

List Return Reasons

Retrieves a list of Return Reasons.

Responses

Response Schema: application/json

required

Array of objects (Return Reason)

Array

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.
description required	string or null Example: "Items that are damaged" A description of the Reason.
id required	string Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ" The return reason's ID
label required	string Example: "Damaged goods" A text that can be displayed to the Customer as a reason.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
parent_return_reason_id required	string or null Example: null The ID of the parent reason.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
value required	string Example: "damaged" The value to identify the reason by.
parent_return_reason	object or null Available if the relation `parent_return_reason` is expanded.
return_reason_children	object Available if the relation `return_reason_children` is expanded.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.returnReasons.list()
.then(({ return_reasons }) => {
  console.log(return_reasons.length);
});

Response samples

Content type

application/json

{"return_reasons": [{"id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
"value": "damaged",
"label": "Damaged goods",
"description": "Items that are damaged",
"parent_return_reason_id": null,
"parent_return_reason": { },
"return_reason_children": { },
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
]
}

Get a Return Reason

Retrieves a Return Reason.

path Parameters

required

string

The id of the Return Reason.

Responses

Response Schema: application/json

required

object (Return Reason)

A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned.

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.
description required	string or null Example: "Items that are damaged" A description of the Reason.
id required	string Example: "rr_01G8X82GCCV2KSQHDBHSSAH5TQ" The return reason's ID
label required	string Example: "Damaged goods" A text that can be displayed to the Customer as a reason.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
parent_return_reason_id required	string or null Example: null The ID of the parent reason.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
value required	string Example: "damaged" The value to identify the reason by.
parent_return_reason	object or null Available if the relation `parent_return_reason` is expanded.
return_reason_children	object Available if the relation `return_reason_children` is expanded.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.returnReasons.retrieve(reason_id)
.then(({ return_reason }) => {
  console.log(return_reason.id);
});

Response samples

Content type

application/json

{"return_reason": {"id": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ",
"value": "damaged",
"label": "Damaged goods",
"description": "Items that are damaged",
"parent_return_reason_id": null,
"parent_return_reason": { },
"return_reason_children": { },
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Returns

Return endpoints that allow handling returns in Medusa.

Create Return

Creates a Return for an Order.

Request Body schema: application/json

order_id required	string The ID of the Order to create the Return from.
required	Array of objects The items to include in the Return.
	object 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.

Responses

Response Schema: application/json

required

object (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.

claim_order_id required	string or null Example: null The ID of the Claim that the Return is a part of.
created_at required	string <date-time> The date with timezone at which the resource was created.
id required	string Example: "ret_01F0YET7XPCMF8RZ0Y151NZV2V" The return's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of the return in case of failure. Learn more how to use the idempotency key.
location_id required	string or null Example: "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK" The id of the stock location the return will be added back.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
no_notification required	boolean or null Example: false When set to true, no notification will be sent related to this return.
order_id required	string or null Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the Order that the Return is made from.
received_at required	string or null <date-time> The date with timezone at which the return was received.
refund_amount required	integer Example: 1000 The amount that should be refunded as a result of the return.
shipping_data required	object or null Example: {} Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.
status required	string Default: "requested" Enum: "requested" "received" "requires_action" "canceled" Status of the Return.
swap_id required	string or null Example: null The ID of the Swap that the Return is a part of.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
	Array of objects (Return Item) The Return Items that will be shipped back to the warehouse. Available if the relation `items` is expanded.
swap	object or null A swap object. Available if the relation `swap` is expanded.
claim_order	object or null A claim order object. Available if the relation `claim_order` is expanded.
order	object or null An order object. Available if the relation `order` is expanded.
	object (Shipping Method) Shipping Methods represent a way in which an Order or Return can be shipped. Shipping Methods are built from a Shipping Option, but may contain additional details, that can be necessary for the Fulfillment Provider to handle the shipment.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_id": "string",
"items": [{"item_id": "string",
"quantity": 0,
"reason_id": "string",
"note": "string"
}
],
"return_shipping": {"option_id": "string"
}
}

Response samples

Content type

application/json

{"return": {"id": "ret_01F0YET7XPCMF8RZ0Y151NZV2V",
"status": "requested",
"items": [{"return_id": null,
"item_id": null,
"return_order": { },
"item": null,
"quantity": null,
"is_requested": null,
"requested_quantity": null,
"received_quantity": null,
"reason_id": null,
"reason": null,
"note": null,
"metadata": { }
}
],
"swap_id": null,
"swap": { },
"claim_order_id": null,
"claim_order": { },
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"shipping_method": {"id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
"shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"claim_order_id": null,
"claim_order": { },
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"swap_id": null,
"swap": { },
"return_id": null,
"return_order": { },
"shipping_option": {"id": null,
"name": null,
"region_id": null,
"region": { },
"profile_id": null,
"profile": null,
"provider_id": null,
"provider": null,
"price_type": null,
"amount": null,
"is_return": null,
"admin_only": null,
"requirements": [ ],
"data": { },
"includes_tax": null,
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"tax_lines": [null
],
"price": 200,
"data": { },
"includes_tax": false,
"subtotal": 8000,
"total": 8200,
"tax_total": 0
},
"shipping_data": { },
"location_id": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK",
"refund_amount": 1000,
"no_notification": false,
"idempotency_key": "string",
"received_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Shipping Options

Shipping Option endpoints that allow handling shipping options in Medusa.

Get Shipping Options

Retrieves a list of Shipping Options.

query Parameters

is_return	boolean Whether return Shipping Options should be included. By default all Shipping Options are returned.
product_ids	string A comma separated list of Product ids to filter Shipping Options by.
region_id	string the Region to retrieve Shipping Options from.

Responses

Response Schema: application/json

required

Array of objects (Priced Shipping Option)

Array

admin_only required	boolean Default: false Flag to indicate if the Shipping Option usage is restricted to admin users.
amount required	integer or null Example: 200 The amount to charge for shipping when the Shipping Option price type is `flat_rate`.
created_at required	string <date-time> The date with timezone at which the resource was created.
data required	object Example: {} The data needed for the Fulfillment Provider to identify the Shipping Option.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
id required	string Example: "so_01G1G5V27GYX4QXNARRQCW1N8T" The shipping option's ID
is_return required	boolean Default: false Flag to indicate if the Shipping Option can be used for Return shipments.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
name required	string Example: "PostFake Standard" The name given to the Shipping Option - this may be displayed to the Customer.
price_type required	string Enum: "flat_rate" "calculated" Example: "flat_rate" The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be `flat_rate` for fixed prices or `calculated` if the Fulfillment Provider can provide price calulations.
profile_id required	string Example: "sp_01G1G5V239ENSZ5MV4JAR737BM" The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.
provider_id required	string Example: "manual" The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
updated_at required	string <date-time> The date with timezone at which the resource was updated.
region	object or null A region object. Available if the relation `region` is expanded.
	object (Shipping Profile) Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.
	object (Fulfillment Provider) Represents a fulfillment provider plugin and holds its installation status.
	Array of objects (Shipping Option Requirement) The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation `requirements` is expanded.
includes_tax	boolean Default: false [EXPERIMENTAL] Does the shipping option price include tax
price_incl_tax	number Price including taxes
	Array of objects An array of applied tax rates
tax_amount	number The taxes applied.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.shippingOptions.list()
.then(({ shipping_options }) => {
  console.log(shipping_options.length);
});

Response samples

Content type

application/json

{"shipping_options": [{"id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"name": "PostFake Standard",
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": { },
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"provider_id": "manual",
"provider": {"id": null,
"is_installed": null
},
"price_type": "flat_rate",
"amount": 200,
"is_return": false,
"admin_only": false,
"requirements": [null
],
"data": { },
"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"
},
"price_incl_tax": 0,
"tax_rates": [{ }
],
"tax_amount": 0
}
]
}

List for Cart

Retrieves a list of Shipping Options available to a cart.

path Parameters

cart_id

required

string

The id of the Cart.

Responses

Response Schema: application/json

required

Array of objects (Priced Shipping Option)

Array

admin_only required	boolean Default: false Flag to indicate if the Shipping Option usage is restricted to admin users.
amount required	integer or null Example: 200 The amount to charge for shipping when the Shipping Option price type is `flat_rate`.
created_at required	string <date-time> The date with timezone at which the resource was created.
data required	object Example: {} The data needed for the Fulfillment Provider to identify the Shipping Option.
deleted_at required	string or null <date-time> The date with timezone at which the resource was deleted.
id required	string Example: "so_01G1G5V27GYX4QXNARRQCW1N8T" The shipping option's ID
is_return required	boolean Default: false Flag to indicate if the Shipping Option can be used for Return shipments.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
name required	string Example: "PostFake Standard" The name given to the Shipping Option - this may be displayed to the Customer.
price_type required	string Enum: "flat_rate" "calculated" Example: "flat_rate" The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be `flat_rate` for fixed prices or `calculated` if the Fulfillment Provider can provide price calulations.
profile_id required	string Example: "sp_01G1G5V239ENSZ5MV4JAR737BM" The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.
provider_id required	string Example: "manual" The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.
region_id required	string Example: "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" The region's ID
updated_at required	string <date-time> The date with timezone at which the resource was updated.
region	object or null A region object. Available if the relation `region` is expanded.
	object (Shipping Profile) Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products.
	object (Fulfillment Provider) Represents a fulfillment provider plugin and holds its installation status.
	Array of objects (Shipping Option Requirement) The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation `requirements` is expanded.
includes_tax	boolean Default: false [EXPERIMENTAL] Does the shipping option price include tax
price_incl_tax	number Price including taxes
	Array of objects An array of applied tax rates
tax_amount	number The taxes applied.

Request samples

JS Client
cURL

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.shippingOptions.listCartOptions(cart_id)
.then(({ shipping_options }) => {
  console.log(shipping_options.length);
});

Response samples

Content type

application/json

{"shipping_options": [{"id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
"name": "PostFake Standard",
"region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
"region": { },
"profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
"profile": {"id": null,
"name": null,
"type": null,
"products": [ ],
"shipping_options": [ ],
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
},
"provider_id": "manual",
"provider": {"id": null,
"is_installed": null
},
"price_type": "flat_rate",
"amount": 200,
"is_return": false,
"admin_only": false,
"requirements": [null
],
"data": { },
"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"
},
"price_incl_tax": 0,
"tax_rates": [{ }
],
"tax_amount": 0
}
]
}

Swaps

Swap endpoints that allow handling swaps in Medusa.

Create a Swap

Creates a Swap on an Order by providing some items to return along with some items to send back

Request Body schema: application/json

order_id required	string The ID of the Order to create the Swap for.
required	Array of objects The items to include in the Return.
required	Array of objects The items to exchange the returned items to.
return_shipping_option	string The ID of the Shipping Option to create the Shipping Method from.

Responses

Response Schema: application/json

required

object (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.

allow_backorder required	boolean Default: false If true, swaps can be completed with items out of stock
canceled_at required	string or null <date-time> The date with timezone at which the Swap was canceled.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The id of the Cart that the Customer will use to confirm the Swap.
confirmed_at required	string or null <date-time> The date with timezone at which the Swap was confirmed by the Customer.
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.
difference_due required	integer or null Example: 0 The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.
fulfillment_status required	string Enum: "not_fulfilled" "fulfilled" "shipped" "partially_shipped" "canceled" "requires_action" Example: "not_fulfilled" The status of the Fulfillment of the Swap.
id required	string Example: "swap_01F0YET86Y9G92D3YDR9Y6V676" The swap's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of the swap 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
no_notification required	boolean or null Example: false If set to true, no notification will be sent related to this swap
order_id required	string Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the Order where the Line Items to be returned where purchased.
payment_status required	string Enum: "not_paid" "awaiting" "captured" "confirmed" "canceled" "difference_refunded" "partially_refunded" "refunded" "requires_action" Example: "not_paid" The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
order	object or null An order object. Available if the relation `order` is expanded.
	Array of objects (Line Item) The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded.
return_order	object or null A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded.
fulfillments	Array of objects The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded.
payment	object or null The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded.
	object (Address) An address.
	Array of objects (Shipping Method) The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded.
cart	object or null A cart object. Available if the relation `cart` is expanded.

Request samples

Payload
JS Client
cURL

Content type

application/json

{"order_id": "string",
"return_items": [{"item_id": "string",
"quantity": 0,
"reason_id": "string",
"note": "string"
}
],
"return_shipping_option": "string",
"additional_items": [{"variant_id": "string",
"quantity": 0
}
]
}

Response samples

Content type

application/json

{"swap": {"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"additional_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,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"return_order": { },
"fulfillments": [{ }
],
"payment": { },
"difference_due": 0,
"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"
}
},
"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
}
],
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"confirmed_at": "2019-08-24T14:15:22Z",
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"allow_backorder": false,
"idempotency_key": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Get by Cart ID

Retrieves a Swap by the id of the Cart used to confirm the Swap.

path Parameters

cart_id

required

string

The id of the Cart

Responses

Response Schema: application/json

required

object (Swap)

allow_backorder required	boolean Default: false If true, swaps can be completed with items out of stock
canceled_at required	string or null <date-time> The date with timezone at which the Swap was canceled.
cart_id required	string or null Example: "cart_01G8ZH853Y6TFXWPG5EYE81X63" The id of the Cart that the Customer will use to confirm the Swap.
confirmed_at required	string or null <date-time> The date with timezone at which the Swap was confirmed by the Customer.
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.
difference_due required	integer or null Example: 0 The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.
fulfillment_status required	string Enum: "not_fulfilled" "fulfilled" "shipped" "partially_shipped" "canceled" "requires_action" Example: "not_fulfilled" The status of the Fulfillment of the Swap.
id required	string Example: "swap_01F0YET86Y9G92D3YDR9Y6V676" The swap's ID
idempotency_key required	string or null Randomly generated key used to continue the completion of the swap 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
no_notification required	boolean or null Example: false If set to true, no notification will be sent related to this swap
order_id required	string Example: "order_01G8TJSYT9M6AVS5N4EMNFS1EK" The ID of the Order where the Line Items to be returned where purchased.
payment_status required	string Enum: "not_paid" "awaiting" "captured" "confirmed" "canceled" "difference_refunded" "partially_refunded" "refunded" "requires_action" Example: "not_paid" The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.
shipping_address_id required	string or null Example: "addr_01G8ZH853YPY9B94857DY91YGW" The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
order	object or null An order object. Available if the relation `order` is expanded.
	Array of objects (Line Item) The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded.
return_order	object or null A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded.
fulfillments	Array of objects The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded.
payment	object or null The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded.
	object (Address) An address.
	Array of objects (Shipping Method) The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded.
cart	object or null A cart object. Available if the relation `cart` is expanded.

Request samples

JS Client
cURL

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

Response samples

Content type

application/json

{"swap": {"id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
"fulfillment_status": "not_fulfilled",
"payment_status": "not_paid",
"order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
"order": { },
"additional_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,
"raw_discount_total": null,
"gift_card_total": null,
"includes_tax": null,
"created_at": null,
"updated_at": null,
"metadata": { }
}
],
"return_order": { },
"fulfillments": [{ }
],
"payment": { },
"difference_due": 0,
"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"
}
},
"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
}
],
"cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
"cart": { },
"confirmed_at": "2019-08-24T14:15:22Z",
"canceled_at": "2019-08-24T14:15:22Z",
"no_notification": false,
"allow_backorder": false,
"idempotency_key": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
}
}
}

Variants

Get Product Variants

Retrieves a list of Product Variants

query Parameters

ids	string A comma separated list of Product Variant ids to filter by.
sales_channel_id	string A sales channel id for result configuration.
expand	string A comma separated list of Product Variant relations to load.
offset	number Default: "0" How many product variants to skip in the result.
limit	number Default: "100" Maximum number of Product Variants to return.
cart_id	string The id of the Cart to set prices based on.
region_id	string The id of the Region to set prices based on.
currency_code	string The currency code to use for price selection.
	string or Array of strings product variant title to search for.
	number or object Filter by available inventory quantity

Responses

Response Schema: application/json

required

Array of objects (Priced Product Variant)

Array

allow_backorder required	boolean Default: false Whether the Product Variant should be purchasable when `inventory_quantity` is 0.
barcode required	string or null Example: null A generic field for a GTIN number that can be used to identify the Product Variant.
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.
ean required	string or null Example: null An EAN barcode number that can be used to identify the Product Variant.
height required	number or null Example: null The height of the Product Variant. May be used in shipping rate calculations.
hs_code required	string or null Example: null The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
id required	string Example: "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" The product variant's ID
inventory_quantity required	integer Example: 100 The current quantity of the item that is stocked.
length required	number or null Example: null The length of the Product Variant. May be used in shipping rate calculations.
manage_inventory required	boolean Default: true Whether Medusa should manage inventory for the Product Variant.
material required	string or null Example: null The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
mid_code required	string or null Example: null The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
origin_country required	string or null Example: null The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
product_id required	string Example: "prod_01G1G5V2MBA328390B5AXJ610F" The ID of the Product that the Product Variant belongs to.
sku required	string or null Example: "shirt-123" The unique stock keeping unit used to identify the Product Variant. This will usually be a unqiue identifer for the item that is to be shipped, and can be referenced across multiple systems.
title required	string Example: "Small" A title that can be displayed for easy identification of the Product Variant.
upc required	string or null Example: null A UPC barcode number that can be used to identify the Product Variant.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
weight required	number or null Example: null The weight of the Product Variant. May be used in shipping rate calculations.
width required	number or null Example: null The width of the Product Variant. May be used in shipping rate calculations.
product	object or null A product object. Available if the relation `product` is expanded.
	Array of objects (Money Amount) The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation `prices` is expanded.
variant_rank	number or null Default: 0 The ranking of this variant
	Array of objects (Product Option Value) The Product Option Values specified for the Product Variant. Available if the relation `options` is expanded.
	Array of objects (Product Variant Inventory Item) The Inventory Items related to the product variant. Available if the relation `inventory_items` is expanded.
purchasable	boolean Only used with the inventory modules. A boolean value indicating whether the Product Variant is purchasable. A variant is purchasable if: inventory is not managed it has no inventory items it is in stock it is backorderable.
original_price	number The original price of the variant without any discounted prices applied.
calculated_price	number The calculated price of the variant. Can be a discounted price.
original_price_incl_tax	number The original price of the variant including taxes.
calculated_price_incl_tax	number The calculated price of the variant including taxes.
original_tax	number The taxes applied on the original price.
calculated_tax	number The taxes applied on the calculated price.
	Array of objects An array of applied tax rates

Request samples

cURL

curl --location --request GET 'https://medusa-url.com/store/variants'

Response samples

Content type

application/json

{"variants": [{"id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
"title": "Small",
"product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
"product": { },
"prices": [null
],
"sku": "shirt-123",
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": 0,
"inventory_quantity": 100,
"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": [null
],
"inventory_items": [null
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"purchasable": true,
"original_price": 0,
"calculated_price": 0,
"original_price_incl_tax": 0,
"calculated_price_incl_tax": 0,
"original_tax": 0,
"calculated_tax": 0,
"tax_rates": [{ }
]
}
]
}

Get a Product Variant

Retrieves a Product Variant by id

path Parameters

variant_id

required

string

The id of the Product Variant.

query Parameters

cart_id	string The id of the Cart to set prices based on.
sales_channel_id	string A sales channel id for result configuration.
region_id	string The id of the Region to set prices based on.
currency_code	string The 3 character ISO currency code to set prices based on. See a list of codes.

Responses

Response Schema: application/json

required

object (Priced 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.

allow_backorder required	boolean Default: false Whether the Product Variant should be purchasable when `inventory_quantity` is 0.
barcode required	string or null Example: null A generic field for a GTIN number that can be used to identify the Product Variant.
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.
ean required	string or null Example: null An EAN barcode number that can be used to identify the Product Variant.
height required	number or null Example: null The height of the Product Variant. May be used in shipping rate calculations.
hs_code required	string or null Example: null The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
id required	string Example: "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" The product variant's ID
inventory_quantity required	integer Example: 100 The current quantity of the item that is stocked.
length required	number or null Example: null The length of the Product Variant. May be used in shipping rate calculations.
manage_inventory required	boolean Default: true Whether Medusa should manage inventory for the Product Variant.
material required	string or null Example: null The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
metadata required	object or null Example: {"car":"white"} An optional key-value map with additional details
mid_code required	string or null Example: null The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
origin_country required	string or null Example: null The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
product_id required	string Example: "prod_01G1G5V2MBA328390B5AXJ610F" The ID of the Product that the Product Variant belongs to.
sku required	string or null Example: "shirt-123" The unique stock keeping unit used to identify the Product Variant. This will usually be a unqiue identifer for the item that is to be shipped, and can be referenced across multiple systems.
title required	string Example: "Small" A title that can be displayed for easy identification of the Product Variant.
upc required	string or null Example: null A UPC barcode number that can be used to identify the Product Variant.
updated_at required	string <date-time> The date with timezone at which the resource was updated.
weight required	number or null Example: null The weight of the Product Variant. May be used in shipping rate calculations.
width required	number or null Example: null The width of the Product Variant. May be used in shipping rate calculations.
product	object or null A product object. Available if the relation `product` is expanded.
	Array of objects (Money Amount) The Money Amounts defined for the Product Variant. Each Money Amount represents a price in a given currency or a price in a specific Region. Available if the relation `prices` is expanded.
variant_rank	number or null Default: 0 The ranking of this variant
	Array of objects (Product Option Value) The Product Option Values specified for the Product Variant. Available if the relation `options` is expanded.
	Array of objects (Product Variant Inventory Item) The Inventory Items related to the product variant. Available if the relation `inventory_items` is expanded.
purchasable	boolean Only used with the inventory modules. A boolean value indicating whether the Product Variant is purchasable. A variant is purchasable if: inventory is not managed it has no inventory items it is in stock it is backorderable.
original_price	number The original price of the variant without any discounted prices applied.
calculated_price	number The calculated price of the variant. Can be a discounted price.
original_price_incl_tax	number The original price of the variant including taxes.
calculated_price_incl_tax	number The calculated price of the variant including taxes.
original_tax	number The taxes applied on the original price.
calculated_tax	number The taxes applied on the calculated price.
	Array of objects An array of applied tax rates

Request samples

cURL

curl --location --request GET 'https://medusa-url.com/store/variants/{id}'

Response samples

Content type

application/json

{"variant": {"id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
"title": "Small",
"product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
"product": { },
"prices": [{"id": null,
"currency_code": null,
"currency": null,
"amount": null,
"min_quantity": null,
"max_quantity": null,
"price_list_id": null,
"price_list": { },
"variant_id": null,
"variant": { },
"region_id": null,
"region": { },
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"sku": "shirt-123",
"barcode": null,
"ean": null,
"upc": null,
"variant_rank": 0,
"inventory_quantity": 100,
"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": null,
"value": null,
"option_id": null,
"option": { },
"variant_id": null,
"variant": { },
"created_at": null,
"updated_at": null,
"deleted_at": null,
"metadata": { }
}
],
"inventory_items": [{"id": null,
"inventory_item_id": null,
"variant_id": null,
"variant": { },
"required_quantity": null,
"created_at": null,
"updated_at": null,
"deleted_at": null
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z",
"metadata": {"car": "white"
},
"purchasable": true,
"original_price": 0,
"calculated_price": 0,
"original_price_incl_tax": 0,
"calculated_price_incl_tax": 0,
"original_tax": 0,
"calculated_tax": 0,
"tax_rates": [{"rate": null,
"name": null,
"code": null
}
]
}
}

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

Sort Order

Auth

Get Current Customer

Authorizations:

Responses

Response Schema: application/json

Request samples

Response samples

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

Check if email exists

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Carts

Create a Cart

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Get a Cart

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Update a Cart

path Parameters

Request Body schema: application/json

Responses

Response Schema: application/json

Request samples

Response samples

Complete a Cart

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Remove Discount

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Add a Line Item