There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.
API Token
Use a user's API Token to send authenticated requests.
How to Add API Token to a User
At the moment, there's no direct way of adding an API Token for a user. The only way it can be done is through directly editing the database.
If you're using a PostgreSQL database, you can run the following commands in your command line to add API token:
psql -d <DB_NAME> -U <DB_USER>
UPDATE public.user SET api_token='<API_TOKEN>' WHERE email='<USER_EMAIL>';
Where:
<DB_NAME>
is the name of the database schema you use for the Medusa server.<DB_USER>
is the name of the user that has privileges over the database schema.<API_TOKEN>
is the API token you want to associate with the user. You can use this tool to generate a random token.<USER_EMAIL>
is the email address of the admin user you want to have this API token.
How to Use the API Token
The API token can be used for Bearer Authentication. It's passed in the Authorization
header as the following:
Authorization: Bearer {api_token}
In this API reference, you'll find in the cURL request samples the use of {api_token}
. This is where you must pass the API token.
If you're following along with the JS Client request samples, you must provide the apiKey
option when creating the Medusa client:
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3, apiKey: '{api_token}' })
If you're using Medusa React, you can pass the apiKey
prop to MedusaProvider
:
<MedusaProvider
apiKey='api_token}'
//...
>
bearer
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 products, you can retrieve their collection by passing to the expand
query parameter the value collection
:
curl "http://localhost:9000/admin/products?expand=collection" \
-H 'Authorization: Bearer {api_token}'
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 products, pass to the expand
query parameter the value variants,collection
:
curl "http://localhost:9000/admin/products?expand=variants,collection" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?expand" \
-H 'Authorization: Bearer {api_token}'
This would retrieve each product with only its properties, without any relations like collection
.
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/admin/products?fields=title" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?fields=title&expand" \
-H 'Authorization: Bearer {api_token}'
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 products:
curl "http://localhost:9000/admin/products?fields=title,handle" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?fields" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?fields&expand" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?title=Shirt" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?title=Blue%20Shirt" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?offset=1" \
-H 'Authorization: Bearer {api_token}'
Boolean
You can pass a boolean value in the form of <parameter_name>=<value>
.
For example:
curl "http://localhost:9000/admin/products?is_giftcard=true" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?created_at[lt]=2023-02-17" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?limit=5" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?order=created_at" \
-H 'Authorization: Bearer {api_token}'
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/admin/products?order=-created_at" \
-H 'Authorization: Bearer {api_token}'
This sorts the products by their created_at
attribute in the descending order.
List Applications
Retrieve a list of applications.
Authorizations:
Responses
Response Schema: application/json
required | Array of objects (OAuth) | ||||||||||||
Array
|
Request samples
- cURL
curl --location --request GET 'https://medusa-url.com/admin/apps' \ --header 'Authorization: Bearer {api_token}'
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "apps": [
- {
- "id": "example_app",
- "display_name": "Example app",
- "application_name": "example",
- "data": { }
}
]
}
Generate Token for App
Generates a token for an application.
Authorizations:
Request Body schema: application/json
application_name required | string Name of the application for the token to be generated for. |
state required | string State of the application. |
code required | string The code for the generated token. |
Responses
Response Schema: application/json
required | object (OAuth) Represent an OAuth app | ||||||||||||
|
Request samples
- Payload
- cURL
{- "application_name": "string",
- "state": "string",
- "code": "string"
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "apps": {
- "id": "example_app",
- "display_name": "Example app",
- "application_name": "example",
- "data": { }
}
}
Get Current User
Gets the currently logged in User.
Authorizations:
Responses
Response Schema: application/json
required | object (User) Represents a User who can manage store settings. | ||||||||||||||||||||
|
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.admin.auth.getSession() .then(({ user }) => { console.log(user.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}
}
User Login
Logs a User in and authorizes them to manage Store settings.
Request Body schema: application/json
email required | string The User's email. |
password required | string The User's password. |
Responses
Response Schema: application/json
required | object (User) Represents a User who can manage store settings. | ||||||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "email": "string",
- "password": "string"
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}
}
User Logout
Deletes the current session for the logged in user.
Authorizations:
Responses
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.admin.auth.deleteSession()
Response samples
- 400
- 404
- 409
- 422
- 500
{- "message": "Discount must be set to dynamic",
- "type": "not_allowed"
}
List Batch Jobs
Retrieve a list of Batch Jobs.
Authorizations:
query Parameters
limit | integer Default: 10 The number of batch jobs to return. |
offset | integer Default: 0 The number of batch jobs to skip before results. |
string or Array of strings Filter by the batch ID | |
type | Array of strings Filter by the batch type |
object Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc. | |
object Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc. | |
object Date comparison for when resulting collections was completed, i.e. less than, greater than etc. | |
object Date comparison for when resulting collections was failed, i.e. less than, greater than etc. | |
object Date comparison for when resulting collections was canceled, i.e. less than, greater than etc. | |
order | string Field used to order retrieved batch jobs |
expand | string (Comma separated) Which fields should be expanded in each order of the result. |
fields | string (Comma separated) Which fields should be included in each order of the result. |
object Date comparison for when resulting collections was created, i.e. less than, greater than etc. | |
object Date comparison for when resulting collections was updated, i.e. less than, greater than etc. |
Responses
Response Schema: application/json
required | Array of objects (Batch Job) |
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.admin.batchJobs.list() .then(({ batch_jobs, limit, offset, count }) => { console.log(batch_jobs.length); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "batch_jobs": [
- {
- "id": "batch_01G8T782965PYFG0751G0Z38B4",
- "type": "product-import",
- "status": "created",
- "created_by": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "created_by_user": {
- "id": null,
- "role": null,
- "email": null,
- "first_name": null,
- "last_name": null,
- "api_token": null,
- "created_at": null,
- "updated_at": null,
- "deleted_at": null,
- "metadata": { }
}, - "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false,
- "result": {
- "errors": [
- {
- "err": [ ],
- "code": "unknown",
- "message": "Method not implemented."
}
], - "stat_descriptors": [
- {
- "key": "product-export-count",
- "name": "Product count to export",
- "message": "There will be 8 products exported by this action"
}
]
}, - "pre_processed_at": "2019-08-24T14:15:22Z",
- "processing_at": "2019-08-24T14:15:22Z",
- "confirmed_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "canceled_at": "2019-08-24T14:15:22Z",
- "failed_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"
}
], - "count": 0,
- "offset": 0,
- "limit": 0
}
Create a Batch Job
Creates a Batch Job.
Authorizations:
Request Body schema: application/json
type required | string Example: "product-export" The type of batch job to start. |
context required | object Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}} Additional infomration regarding the batch to be used for processing. |
dry_run | boolean Default: false Set a batch job in dry_run mode to get some information on what will be done without applying any modifications. |
Responses
Request samples
- Payload
- JS Client
- cURL
{- "type": "product-export",
- "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false
}
Response samples
- 201
- 400
- 404
- 409
- 422
- 500
{- "batch_job": {
- "id": "batch_01G8T782965PYFG0751G0Z38B4",
- "type": "product-import",
- "status": "created",
- "created_by": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "created_by_user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}, - "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false,
- "result": {
- "errors": [
- {
- "err": [ ],
- "code": "unknown",
- "message": "Method not implemented."
}
], - "stat_descriptors": [
- {
- "key": "product-export-count",
- "name": "Product count to export",
- "message": "There will be 8 products exported by this action"
}
]
}, - "pre_processed_at": "2019-08-24T14:15:22Z",
- "processing_at": "2019-08-24T14:15:22Z",
- "confirmed_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "canceled_at": "2019-08-24T14:15:22Z",
- "failed_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"
}
}
Get a Batch Job
Retrieves a Batch Job.
Authorizations:
path Parameters
id required | string The ID of the Batch Job |
Responses
Response Schema: application/json
required | object (Batch Job) A Batch Job. | ||||||||||||||||||||||||||||||||||
|
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.admin.batchJobs.retrieve(batch_job_id) .then(({ batch_job }) => { console.log(batch_job.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "batch_job": {
- "id": "batch_01G8T782965PYFG0751G0Z38B4",
- "type": "product-import",
- "status": "created",
- "created_by": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "created_by_user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}, - "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false,
- "result": {
- "errors": [
- {
- "err": [ ],
- "code": "unknown",
- "message": "Method not implemented."
}
], - "stat_descriptors": [
- {
- "key": "product-export-count",
- "name": "Product count to export",
- "message": "There will be 8 products exported by this action"
}
]
}, - "pre_processed_at": "2019-08-24T14:15:22Z",
- "processing_at": "2019-08-24T14:15:22Z",
- "confirmed_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "canceled_at": "2019-08-24T14:15:22Z",
- "failed_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"
}
}
Cancel a Batch Job
Marks a batch job as canceled
Authorizations:
path Parameters
id required | string The ID of the batch job. |
Responses
Response Schema: application/json
required | object (Batch Job) A Batch Job. | ||||||||||||||||||||||||||||||||||
|
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.admin.batchJobs.cancel(batch_job_id) .then(({ batch_job }) => { console.log(batch_job.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "batch_job": {
- "id": "batch_01G8T782965PYFG0751G0Z38B4",
- "type": "product-import",
- "status": "created",
- "created_by": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "created_by_user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}, - "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false,
- "result": {
- "errors": [
- {
- "err": [ ],
- "code": "unknown",
- "message": "Method not implemented."
}
], - "stat_descriptors": [
- {
- "key": "product-export-count",
- "name": "Product count to export",
- "message": "There will be 8 products exported by this action"
}
]
}, - "pre_processed_at": "2019-08-24T14:15:22Z",
- "processing_at": "2019-08-24T14:15:22Z",
- "confirmed_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "canceled_at": "2019-08-24T14:15:22Z",
- "failed_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"
}
}
Confirm a Batch Job
Confirms that a previously requested batch job should be executed.
Authorizations:
path Parameters
id required | string The ID of the batch job. |
Responses
Response Schema: application/json
required | object (Batch Job) A Batch Job. | ||||||||||||||||||||||||||||||||||
|
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.admin.batchJobs.confirm(batch_job_id) .then(({ batch_job }) => { console.log(batch_job.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "batch_job": {
- "id": "batch_01G8T782965PYFG0751G0Z38B4",
- "type": "product-import",
- "status": "created",
- "created_by": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "created_by_user": {
- "id": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V",
- "role": "admin",
- "email": "user@example.com",
- "first_name": "Levi",
- "last_name": "Bogan",
- "api_token": 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"
}
}, - "context": {
- "shape": {
- "prices": [
- {
- "region": null,
- "currency_code": "eur"
}
], - "dynamicImageColumnCount": 4,
- "dynamicOptionColumnCount": 2
}, - "list_config": {
- "skip": 0,
- "take": 50,
- "order": {
- "created_at": "DESC"
}, - "relations": [
- "variants",
- "variant.prices",
- "images"
]
}
}, - "dry_run": false,
- "result": {
- "errors": [
- {
- "err": [ ],
- "code": "unknown",
- "message": "Method not implemented."
}
], - "stat_descriptors": [
- {
- "key": "product-export-count",
- "name": "Product count to export",
- "message": "There will be 8 products exported by this action"
}
]
}, - "pre_processed_at": "2019-08-24T14:15:22Z",
- "processing_at": "2019-08-24T14:15:22Z",
- "confirmed_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "canceled_at": "2019-08-24T14:15:22Z",
- "failed_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"
}
}
List Collections
Retrieve a list of Product Collection.
Authorizations:
query Parameters
limit | integer Default: 10 The number of collections to return. |
offset | integer Default: 0 The number of collections to skip before the results. |
title | string The title of collections to return. |
handle | string The handle of collections to return. |
q | string a search term to search titles and handles. |
discount_condition_id | string The discount condition id on which to filter the product collections. |
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 deleted. |
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 }) // must be previously logged in or use api token medusa.admin.collections.list() .then(({ collections, limit, offset, count }) => { console.log(collections.length); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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
}
Create a Collection
Creates a Product Collection.
Authorizations:
Request Body schema: application/json
title required | string The title to identify the Collection by. |
handle | string An optional handle to be used in slugs, if none is provided we will kebab-case the title. |
metadata | object An optional set of key-value pairs to hold additional information. |
Responses
Response Schema: application/json
required | object (Product Collection) Product Collections represents a group of Products that are related. | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "title": "string",
- "handle": "string",
- "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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"
}
}
}
Get a Collection
Retrieves a Product Collection.
Authorizations:
path Parameters
id 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. | ||||||||||||||||
|
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.admin.collections.retrieve(collection_id) .then(({ collection }) => { console.log(collection.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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"
}
}
}
Update a Collection
Updates a Product Collection.
Authorizations:
path Parameters
id required | string The ID of the Collection. |
Request Body schema: application/json
title | string The title to identify the Collection by. |
handle | string An optional handle to be used in slugs, if none is provided we will kebab-case the title. |
metadata | object An optional set of key-value pairs to hold additional information. |
Responses
Response Schema: application/json
required | object (Product Collection) Product Collections represents a group of Products that are related. | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "title": "string",
- "handle": "string",
- "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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"
}
}
}
Delete a Collection
Deletes a Product Collection.
Authorizations:
path Parameters
id required | string The ID of the Collection. |
Responses
Response Schema: application/json
id required | string The ID of the deleted Collection |
object required | string Default: "product-collection" The type of the object that was deleted. |
deleted required | boolean Default: true Whether the collection was deleted successfully or not. |
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.admin.collections.delete(collection_id) .then(({ id, object, deleted }) => { console.log(id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "id": "string",
- "object": "product-collection",
- "deleted": true
}
Update Products
Updates products associated with a Product Collection
Authorizations:
path Parameters
id required | string The ID of the Collection. |
Request Body schema: application/json
product_ids required | Array of strings An array of Product IDs to add to the Product Collection. |
Responses
Response Schema: application/json
required | object (Product Collection) Product Collections represents a group of Products that are related. | ||||||||||||||||
|
Request samples
- Payload
- cURL
{- "product_ids": [
- "string"
]
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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"
}
}
}
Remove Product
Removes products associated with a Product Collection
Authorizations:
path Parameters
id required | string The ID of the Collection. |
Request Body schema: application/json
product_ids required | Array of strings An array of Product IDs to remove from the Product Collection. |
Responses
Response Schema: application/json
id required | string The ID of the collection |
object required | string Default: "product-collection" The type of object the removal was executed on |
removed_products required | Array of strings The IDs of the products removed from the collection |
Request samples
- Payload
- cURL
{- "product_ids": [
- "string"
]
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "id": "string",
- "object": "product-collection",
- "removed_products": [
- "string"
]
}
List Currency
Retrieves a list of Currency
query Parameters
code | string Code of the currency to search for. |
includes_tax | boolean Search for tax inclusive currencies. |
order | string order to retrieve products in. |
offset | number Default: "0" How many products to skip in the result. |
limit | number Default: "20" Limit the number of products returned. |
Responses
Response Schema: application/json
required | Array of objects (Currency) |
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.admin.currencies.list() .then(({ currencies, count, offset, limit }) => { console.log(currencies.length); });
Response samples
- 200
{- "currencies": [
- {
- "code": "usd",
- "symbol": "$",
- "symbol_native": "$",
- "name": "US Dollar",
- "includes_tax": false
}
], - "count": 0,
- "offset": 0,
- "limit": 0
}
Update a Currency
Update a Currency
path Parameters
code required | string The code of the Currency. |
Request Body schema: application/json
includes_tax | boolean [EXPERIMENTAL] Tax included in prices of currency. |
Responses
Response Schema: application/json
required | object (Currency) Currency | ||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "includes_tax": true
}
Response samples
- 200
{- "currency": {
- "code": "usd",
- "symbol": "$",
- "symbol_native": "$",
- "name": "US Dollar",
- "includes_tax": false
}
}
List Customer Groups
Retrieve a list of customer groups.
Authorizations:
query Parameters
q | string Query used for searching customer group names. |
offset | integer Default: 0 How many groups to skip in the result. |
order | string the field used to order the customer groups. |
discount_condition_id | string The discount condition id on which to filter the customer groups. |
string or Array of strings or object Filter by the customer group ID | |
name | Array of strings Filter by the customer group name |
object Date comparison for when resulting customer groups were created. | |
object Date comparison for when resulting customer groups were updated. | |
limit | integer Default: 10 Limit the number of customer groups returned. |
expand | string (Comma separated) Which fields should be expanded in each customer groups of the result. |
Responses
Response Schema: application/json
required | Array of objects (Customer Group) |
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.admin.customerGroups.list() .then(({ customer_groups, limit, offset, count }) => { console.log(customer_groups.length); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_groups": [
- {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "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
}
Create a Customer Group
Creates a CustomerGroup.
Authorizations:
Request Body schema: application/json
name required | string Name of the customer group |
metadata | object Metadata for the customer. |
Responses
Response Schema: application/json
required | object (Customer Group) Represents a customer group | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "name": "string",
- "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_group": {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "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 Group
Retrieves a Customer Group.
Authorizations:
path Parameters
id required | string The ID of the Customer Group. |
query Parameters
expand | string (Comma separated) Which fields should be expanded in the customer group. |
fields | string (Comma separated) Which fields should be included in the customer group. |
Responses
Response Schema: application/json
required | object (Customer Group) Represents a customer group | ||||||||||||||||
|
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.admin.customerGroups.retrieve(customer_group_id) .then(({ customer_group }) => { console.log(customer_group.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_group": {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "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 Customer Group
Update a CustomerGroup.
Authorizations:
path Parameters
id required | string The ID of the customer group. |
Request Body schema: application/json
name | string Name of the customer group |
metadata | object Metadata for the customer. |
Responses
Response Schema: application/json
required | object (Customer Group) Represents a customer group | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "name": "string",
- "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_group": {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "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 a Customer Group
Deletes a CustomerGroup.
Authorizations:
path Parameters
id required | string The ID of the Customer Group |
Responses
Response Schema: application/json
id required | string The ID of the deleted customer group. |
object required | string Default: "customer_group" The type of the object that was deleted. |
deleted required | boolean Default: true Whether the customer group was deleted successfully or not. |
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.admin.customerGroups.delete(customer_group_id) .then(({ id, object, deleted }) => { console.log(id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "id": "string",
- "object": "customer_group",
- "deleted": true
}
List Customers
Retrieves a list of customers in a customer group
Authorizations:
path Parameters
id required | string The ID of the customer group. |
query Parameters
limit | integer Default: 50 The number of items to return. |
offset | integer Default: 0 The items to skip before result. |
expand | string (Comma separated) Which fields should be expanded in each customer. |
q | string a search term to search email, first_name, and last_name. |
Responses
Response Schema: application/json
required | Array of objects (Customer) |
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.admin.customerGroups.listCustomers(customer_group_id) .then(({ customers }) => { console.log(customers.length); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customers": [
- {
- "id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
- "email": "user@example.com",
- "first_name": "Arno",
- "last_name": "Willms",
- "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_addresses": [
- null
], - "phone": 16128234334802,
- "has_account": false,
- "orders": [
- { }
], - "groups": [
- 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
}
Add Customers
Adds a list of customers, represented by id's, to a customer group.
Authorizations:
path Parameters
id required | string The ID of the customer group. |
Request Body schema: application/json
required | Array of objects The ids of the customers to add | ||
Array
|
Responses
Response Schema: application/json
required | object (Customer Group) Represents a customer group | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "customer_ids": [
- {
- "id": "string"
}
]
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_group": {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "metadata": {
- "car": "white"
}
}
}
Remove Customers
Removes a list of customers, represented by id's, from a customer group.
Authorizations:
path Parameters
id required | string The ID of the customer group. |
Request Body schema: application/json
required | Array of objects The ids of the customers to remove | ||
Array
|
Responses
Response Schema: application/json
required | object (Customer Group) Represents a customer group | ||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "customer_ids": [
- {
- "id": "string"
}
]
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customer_group": {
- "id": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63",
- "name": "VIP",
- "customers": [
- { }
], - "price_lists": [
- { }
], - "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 Customers
Retrieves a list of Customers.
Authorizations:
query Parameters
limit | integer Default: 50 The number of items to return. |
offset | integer Default: 0 The items to skip before result. |
expand | string (Comma separated) Which fields should be expanded in each customer. |
q | string a search term to search email, first_name, and last_name. |
Responses
Response Schema: application/json
required | Array of objects (Customer) |
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.admin.customers.list() .then(({ customers, limit, offset, count }) => { console.log(customers.length); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "customers": [
- {
- "id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
- "email": "user@example.com",
- "first_name": "Arno",
- "last_name": "Willms",
- "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_addresses": [
- null
], - "phone": 16128234334802,
- "has_account": false,
- "orders": [
- { }
], - "groups": [
- 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
}
Create a Customer
Creates a Customer.
Authorizations:
Request Body schema: application/json
email required | string <email> The customer's email. |
first_name required | string The customer's first name. |
last_name required | string The customer's last name. |
password required | string <password> The customer's password. |
phone | string The customer's phone number. |
metadata | object An optional set of key-value pairs to hold additional information. |
Responses
Request samples
- Payload
- JS Client
- cURL
{- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "password": "pa$$word",
- "phone": "string",
- "metadata": { }
}
Response samples
- 201
- 400
- 404
- 409
- 422
- 500
{- "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.
Authorizations:
path Parameters
id required | string The ID of the Customer. |
query Parameters
expand | string (Comma separated) Which fields should be expanded in the customer. |
fields | string (Comma separated) Which fields should be included in the customer. |
Responses
Response Schema: application/json
required | object (Customer) Represents a customer | ||||||||||||||||||||||||||||||
|
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.admin.customers.retrieve(customer_id) .then(({ customer }) => { console.log(customer.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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 Customer
Updates a Customer.
Authorizations:
path Parameters
id required | string The ID of the Customer. |
query Parameters
expand | string (Comma separated) Which fields should be expanded in each customer. |
fields | string (Comma separated) Which fields should be retrieved in each customer. |
Request Body schema: application/json
string <email> The Customer's email. | |
first_name | string The Customer's first name. |
last_name | string The Customer's last name. |
phone | string The Customer's phone number. |
password | string <password> The Customer's password. |
Array of objects A list of customer groups to which the customer belongs. | |
metadata | object An optional set of key-value pairs to hold additional information. |
Responses
Response Schema: application/json
required | object (Customer) Represents a customer | ||||||||||||||||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "phone": "string",
- "password": "pa$$word",
- "groups": [
- {
- "id": "string"
}
], - "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "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 Discounts
Retrieves a list of Discounts
Authorizations:
query Parameters
q | string Search query applied on the code field. |
object Discount Rules filters to apply on the search | |
is_dynamic | boolean Return only dynamic discounts. |
is_disabled | boolean Return only disabled discounts. |
limit | number Default: "20" The number of items in the response |
offset | number Default: "0" The offset of items in response |
expand | string Comma separated list of relations to include in the results. |
Responses
Response Schema: application/json
required | Array of objects (Discount) |
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.admin.discounts.list() .then(({ discounts, limit, offset, count }) => { console.log(discounts.id); });
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "discounts": [
- {
- "id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
- "code": "10DISC",
- "is_dynamic": false,
- "rule_id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
- "rule": {
- "id": null,
- "type": null,
- "description": null,
- "value": null,
- "allocation": null,
- "conditions": [ ],
- "created_at": null,
- "updated_at": null,
- "deleted_at": null,
- "metadata": { }
}, - "is_disabled": false,
- "parent_discount_id": "disc_01G8ZH853YPY9B94857DY91YGW",
- "parent_discount": { },
- "starts_at": "2019-08-24T14:15:22Z",
- "ends_at": "2019-08-24T14:15:22Z",
- "valid_duration": "P3Y6M4DT12H30M5S",
- "regions": [
- null
], - "usage_limit": 100,
- "usage_count": 50,
- "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
}
Creates a Discount
Creates a Discount with a given set of rules that define how the Discount behaves.
Authorizations:
query Parameters
expand | string (Comma separated) Which fields should be expanded in the results. |
fields | string (Comma separated) Which fields should be retrieved in the results. |
Request Body schema: application/json
code required | string A unique code that will be used to redeem the Discount |
required | object The Discount Rule that defines how Discounts are calculated |
regions required | Array of strings A list of Region ids representing the Regions in which the Discount can be used. |
is_dynamic | boolean Default: false Whether the Discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated codes that all have to follow a common set of rules. |
is_disabled | boolean Default: false Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers. |
starts_at | string <date-time> The time at which the Discount should be available. |
ends_at | string <date-time> The time at which the Discount should no longer be available. |
valid_duration | string Example: "P3Y6M4DT12H30M5S" Duration the discount runs between |
usage_limit | number Maximum times the discount can be used |
metadata | object An optional set of key-value pairs to hold additional information. |
Responses
Response Schema: application/json
required | object (Discount) Represents a discount that can be applied to a cart for promotional purposes. | ||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
- JS Client
- cURL
{- "code": "string",
- "is_dynamic": false,
- "rule": {
- "description": "string",
- "type": "fixed",
- "value": 0,
- "allocation": "total",
- "conditions": [
- {
- "operator": null,
- "products": [ ],
- "product_types": [ ],
- "product_collections": [ ],
- "product_tags": [ ],
- "customer_groups": [ ]
}
]
}, - "is_disabled": false,
- "starts_at": "2019-08-24T14:15:22Z",
- "ends_at": "2019-08-24T14:15:22Z",
- "valid_duration": "P3Y6M4DT12H30M5S",
- "regions": [
- "string"
], - "usage_limit": 0,
- "metadata": { }
}
Response samples
- 200
- 400
- 404
- 409
- 422
- 500
{- "discount": {
- "id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
- "code": "10DISC",
- "is_dynamic": false,
- "rule_id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
- "rule": {
- "id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
- "type": "percentage",
- "description": "10 Percent",
- "value": 10,
- "allocation": "total",
- "conditions": [
- { }
], - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "metadata": {