openapi: 3.0.0 info: version: 1.0.0 title: Medusa Admin API description: > API reference for Medusa's Admin endpoints. All endpoints are prefixed with `/admin`. ## Authentication There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID. ## 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. For example, when you list customers you can also retrieve their groups by passing to the `expand` query parameter the value `groups`. 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 orders and the groups of a customer, pass to the `expand` query parameter the value `groups,orders`. Please note that the parameters you pass to `expand` replace any relations that are expanded by default. ## 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. You can pass more than one field by seperating the field names in the `fields` query parameter with a comma. Only the fields you pass to `field` will be retrieved and returned in the response. Any fields that are returned by default will not be returned in this case. This does not affect relations. For example, to only select the `title` and `description` fields of a product, pass to the `fields` query parameter the value `title,description`. ## 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. ### Response Fields In listing fields, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`. Similarly 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`. license: name: MIT url: 'https://github.com/medusajs/medusa/blob/master/LICENSE' tags: - name: Auth description: >- Auth endpoints that allow authorization of admin Users and manages their sessions. - name: App description: App endpoints that allow handling apps in Medusa. x-resourceId: OAuth - name: Batch Job description: Batch Job endpoints that allow handling batch jobs in Medusa. x-resourceId: batch_job - name: Claim description: Claim endpoints that allow handling claims in Medusa. x-resourceId: claim_order - name: Collection description: Collection endpoints that allow handling collections in Medusa. x-resourceId: product_collection - name: Customer description: Customer endpoints that allow handling customers in Medusa. x-resourceId: customer - name: Customer Group description: Customer Group endpoints that allow handling customer groups in Medusa. x-resourceId: customer_group - name: Discount description: Discount endpoints that allow handling discounts in Medusa. x-resourceId: discount - name: Discount Condition description: >- Discount Condition endpoints that allow handling discount conditions in Medusa. x-resourceId: discount_condition - name: Draft Order description: Draft Order endpoints that allow handling draft orders in Medusa. x-resourceId: draft-order - name: Gift Card description: Gift Card endpoints that allow handling gift cards in Medusa. x-resourceId: gift_card - name: Invite description: Invite endpoints that allow handling invites in Medusa. x-resourceId: invite - name: Note description: Note endpoints that allow handling notes in Medusa. x-resourceId: note - name: Notification description: Notification endpoints that allow handling notifications in Medusa. x-resourceId: notification - name: Order description: Order endpoints that allow handling orders in Medusa. x-resourceId: order - name: Price List description: Price List endpoints that allow handling price lists in Medusa. x-resourceId: price_list - name: Product description: Product endpoints that allow handling products in Medusa. x-resourceId: product - name: Product Tag description: Product Tag endpoints that allow handling product tags in Medusa. x-resourceId: product_tag - name: Product Type description: Product Types endpoints that allow handling product types in Medusa. x-resourceId: product_type - name: Product Variant description: Product Variant endpoints that allow handling product variants in Medusa. x-resourceId: product_variant - name: Region description: Region endpoints that allow handling regions in Medusa. x-resourceId: region - name: Return Reason description: Return Reason endpoints that allow handling return reasons in Medusa. x-resourceId: return_reason - name: Return description: Return endpoints that allow handling returns in Medusa. x-resourceId: return - name: Sales Channel description: Sales Channel endpoints that allow handling sales channels in Medusa. x-resourceId: sales_channel - name: Shipping Option description: Shipping Option endpoints that allow handling shipping options in Medusa. x-resourceId: shipping_option - name: Shipping Profile description: >- Shipping Profile endpoints that allow handling shipping profiles in Medusa. x-resourceId: shipping_profile - name: Store description: Store endpoints that allow handling stores in Medusa. x-resourceId: store - name: Swap description: Swap endpoints that allow handling swaps in Medusa. x-resourceId: swap - name: Tax Rate description: Tax Rate endpoints that allow handling tax rates in Medusa. x-resourceId: tax_rate - name: Upload description: Upload endpoints that allow handling uploads in Medusa. - name: User description: User endpoints that allow handling users in Medusa. x-resourceId: user servers: - url: 'https://api.medusa-commerce.com/admin' paths: /apps/authorizations: post: operationId: PostApps summary: Generate Token for App description: Generates a token for an application. x-authenticated: true requestBody: content: application/json: schema: required: - application_name - state - code properties: application_name: type: string description: Name of the application for the token to be generated for. state: type: string description: State of the application. code: type: string description: The code for the generated token. x-codeSamples: - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/apps/authorizations' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "application_name": "example", "state": "ready", "code": "token" }' security: - api_token: [] - cookie_auth: [] tags: - App responses: '200': description: OK content: application/json: schema: properties: apps: $ref: '#/components/schemas/OAuth' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /apps: get: operationId: GetApps summary: List Applications description: Retrieve a list of applications. x-authenticated: true x-codeSamples: - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/apps' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - App responses: '200': description: OK content: application/json: schema: properties: apps: type: array items: $ref: '#/components/schemas/OAuth' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /auth: post: operationId: PostAuth summary: User Login x-authenticated: false description: Logs a User in and authorizes them to manage Store settings. parameters: [] requestBody: content: application/json: schema: type: object required: - email - password properties: email: type: string description: The User's email. password: type: string description: The User's password. x-codeSamples: - lang: JavaScript label: JS Client source: > import Medusa from "@medusajs/medusa-js" const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) medusa.admin.auth.createSession({ email: 'user@example.com', password: 'supersecret' }).then((({ user }) => { console.log(user.id); }); - lang: Shell label: cURL source: | curl --location --request POST 'https://medusa-url.com/admin/auth' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com", "password": "supersecret" }' tags: - Auth responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/incorrect_credentials' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteAuth summary: User Logout x-authenticated: true description: Deletes the current session for the logged in user. x-codeSamples: - lang: JavaScript label: JS Client source: > 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() - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/auth' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Auth responses: '200': description: OK '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetAuth summary: Get Current User x-authenticated: true description: Gets the currently logged in User. x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/auth' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Auth responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/batch-jobs/{id}/cancel': post: operationId: PostBatchJobsBatchJobCancel summary: Cancel a Batch Job description: Marks a batch job as canceled x-authenticated: true parameters: - in: path name: id required: true description: The ID of the batch job. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Batch Job responses: '200': description: OK content: application/json: schema: properties: batch_job: $ref: '#/components/schemas/batch_job' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/batch-jobs/{id}/confirm': post: operationId: PostBatchJobsBatchJobConfirmProcessing summary: Confirm a Batch Job description: Confirms that a previously requested batch job should be executed. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the batch job. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Batch Job responses: '200': description: OK content: application/json: schema: properties: batch_job: $ref: '#/components/schemas/batch_job' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /batch-jobs: post: operationId: PostBatchJobs summary: Create a Batch Job description: Creates a Batch Job. x-authenticated: true requestBody: content: application/json: schema: required: - type - context properties: type: type: string description: The type of batch job to start. example: product-export context: type: object description: >- Additional infomration regarding the batch to be used for processing. 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 dry_run: type: boolean description: >- Set a batch job in dry_run mode to get some information on what will be done without applying any modifications. default: false x-codeSamples: - lang: JavaScript label: JS Client source: > 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.create({ type: 'product-export', context: {}, dry_run: false }).then((({ batch_job }) => { console.log(batch_job.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/batch-jobs' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {api_token}' \ --data-raw '{ "type": "product-export", "context": { } }' security: - api_token: [] - cookie_auth: [] tags: - Batch Job responses: '201': description: OK content: application/json: schema: properties: batch_job: $ref: '#/components/schemas/batch_job' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetBatchJobs summary: List Batch Jobs description: Retrieve a list of Batch Jobs. x-authenticated: true parameters: - in: query name: limit description: The number of batch jobs to return. schema: type: integer default: 10 - in: query name: offset description: The number of batch jobs to skip before results. schema: type: integer default: 0 - in: query name: id style: form explode: false description: Filter by the batch ID schema: oneOf: - type: string description: batch job ID - type: array description: multiple batch job IDs items: type: string - in: query name: type style: form explode: false description: Filter by the batch type schema: type: array items: type: string - in: query name: confirmed_at style: form explode: false description: >- Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: pre_processed_at style: form explode: false description: >- Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: completed_at style: form explode: false description: >- Date comparison for when resulting collections was completed, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: failed_at style: form explode: false description: >- Date comparison for when resulting collections was failed, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: canceled_at style: form explode: false description: >- Date comparison for when resulting collections was canceled, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: order description: Field used to order retrieved batch jobs schema: type: string - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each order of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each order of the result. schema: type: string - in: query name: created_at style: form explode: false description: >- Date comparison for when resulting collections was created, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at style: form explode: false description: >- Date comparison for when resulting collections was updated, i.e. less than, greater than etc. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/batch-jobs' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Batch Job responses: '200': description: OK content: application/json: schema: properties: batch_jobs: type: array items: $ref: '#/components/schemas/batch_job' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/batch-jobs/{id}': get: operationId: GetBatchJobsBatchJob summary: Get a Batch Job description: Retrieves a Batch Job. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Batch Job schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/batch-jobs/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Batch Job responses: '200': description: OK content: application/json: schema: properties: batch_job: $ref: '#/components/schemas/batch_job' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/collections/{id}/products/batch': post: operationId: PostProductsToCollection summary: Update Products description: Updates products associated with a Product Collection x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Collection. schema: type: string requestBody: content: application/json: schema: required: - product_ids properties: product_ids: description: An array of Product IDs to add to the Product Collection. type: array items: description: The ID of a Product to add to the Product Collection. type: string x-codeSamples: - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_ids": [ "prod_01G1G5V2MBA328390B5AXJ610F" ] }' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: collection: $ref: '#/components/schemas/product_collection' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteProductsFromCollection summary: Remove Product description: Removes products associated with a Product Collection x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Collection. schema: type: string requestBody: content: application/json: schema: required: - product_ids properties: product_ids: description: >- An array of Product IDs to remove from the Product Collection. type: array items: description: The ID of a Product to add to the Product Collection. type: string x-codeSamples: - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_ids": [ "prod_01G1G5V2MBA328390B5AXJ610F" ] }' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the collection object: type: string description: The type of object the removal was executed on default: product-collection removed_products: description: The IDs of the products removed from the collection type: array items: description: The ID of a Product to add to the Product Collection. type: string '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /collections: post: operationId: PostCollections summary: Create a Collection description: Creates a Product Collection. x-authenticated: true requestBody: content: application/json: schema: required: - title properties: title: type: string description: The title to identify the Collection by. handle: type: string description: >- An optional handle to be used in slugs, if none is provided we will kebab-case the title. metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.create({ title: 'New Collection' }) .then(({ collection }) => { console.log(collection.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/collections' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "New Collection" }' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: collection: $ref: '#/components/schemas/product_collection' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetCollections summary: List Collections description: Retrieve a list of Product Collection. x-authenticated: true parameters: - in: query name: limit description: The number of collections to return. schema: type: integer default: 10 - in: query name: offset description: The number of collections to skip before the results. schema: type: integer default: 0 - in: query name: title description: The title of collections to return. schema: type: string - in: query name: handle description: The handle of collections to return. schema: type: string - in: query name: q description: a search term to search titles and handles. schema: type: string - in: query name: discount_condition_id description: >- The discount condition id on which to filter the product collections. schema: type: string - in: query name: created_at description: Date comparison for when resulting collections were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting collections were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: deleted_at description: Date comparison for when resulting collections were deleted. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/collections' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: collections: type: array items: $ref: '#/components/schemas/product_collection' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/collections/{id}': delete: operationId: DeleteCollectionsCollection summary: Delete a Collection description: Deletes a Product Collection. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Collection. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Collection object: type: string description: The type of the object that was deleted. default: product-collection deleted: type: boolean description: Whether the collection was deleted successfully or not. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetCollectionsCollection summary: Get a Collection description: Retrieves a Product Collection. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product Collection schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/collections/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: collection: $ref: '#/components/schemas/product_collection' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostCollectionsCollection summary: Update a Collection description: Updates a Product Collection. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Collection. schema: type: string requestBody: content: application/json: schema: properties: title: type: string description: The title to identify the Collection by. handle: type: string description: >- An optional handle to be used in slugs, if none is provided we will kebab-case the title. metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.update(collection_id, { title: 'New Collection' }) .then(({ collection }) => { console.log(collection.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/collections/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "New Collection" }' security: - api_token: [] - cookie_auth: [] tags: - Collection responses: '200': description: OK content: application/json: schema: properties: collection: $ref: '#/components/schemas/product_collection' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /currencies: get: operationId: GetCurrencies summary: List Currency description: Retrieves a list of Currency x-authenticated: true parameters: - in: query name: code description: Code of the currency to search for. schema: type: string - in: query name: includes_tax description: Search for tax inclusive currencies. schema: type: boolean - in: query name: order description: order to retrieve products in. schema: type: string - in: query name: offset description: How many products to skip in the result. schema: type: number default: '0' - in: query name: limit description: Limit the number of products returned. schema: type: number default: '20' x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/currencies' \ --header 'Authorization: Bearer {api_token}' tags: - Currency responses: '200': description: OK content: application/json: schema: properties: currencies: type: array items: $ref: '#/components/schemas/currency' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '/currencies/{code}': post: operationId: PostCurrenciesCurrency summary: Update a Currency description: Update a Currency x-authenticated: true parameters: - in: path name: code required: true description: The code of the Currency. schema: type: string requestBody: content: application/json: schema: properties: includes_tax: type: boolean description: '[EXPERIMENTAL] Tax included in prices of currency.' x-codeSamples: - lang: JavaScript label: JS Client source: > 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.update(code, { includes_tax: true }) .then(({ currency }) => { console.log(currency.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/currencies/{code}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "includes_tax": true }' tags: - Currency responses: '200': description: OK content: application/json: schema: properties: currency: $ref: '#/components/schemas/currency' '/customer-groups/{id}/customers/batch': post: operationId: PostCustomerGroupsGroupCustomersBatch summary: Add Customers description: 'Adds a list of customers, represented by id''s, to a customer group.' x-authenticated: true parameters: - in: path name: id required: true description: The ID of the customer group. schema: type: string requestBody: content: application/json: schema: required: - customer_ids properties: customer_ids: description: The ids of the customers to add type: array items: required: - id properties: id: description: ID of the customer type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.addCustomers(customer_group_id, { customer_ids: [ { id: customer_id } ] }) .then(({ customer_group }) => { console.log(customer_group.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customer_ids": [ { "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_group: $ref: '#/components/schemas/customer_group' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteCustomerGroupsGroupCustomerBatch summary: Remove Customers description: 'Removes a list of customers, represented by id''s, from a customer group.' x-authenticated: true parameters: - in: path name: id required: true description: The ID of the customer group. schema: type: string requestBody: content: application/json: schema: required: - customer_ids properties: customer_ids: description: The ids of the customers to remove type: array items: required: - id properties: id: description: ID of the customer type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.removeCustomers(customer_group_id, { customer_ids: [ { id: customer_id } ] }) .then(({ customer_group }) => { console.log(customer_group.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customer_ids": [ { "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_group: $ref: '#/components/schemas/customer_group' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /customer-groups: post: operationId: PostCustomerGroups summary: Create a Customer Group description: Creates a CustomerGroup. x-authenticated: true parameters: [] x-codeSamples: - lang: JavaScript label: JS Client source: > 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.create({ name: 'VIP' }) .then(({ customer_group }) => { console.log(customer_group.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/customer-groups' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "VIP" }' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_group: $ref: '#/components/schemas/customer_group' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: Name of the customer group metadata: type: object description: Metadata for the customer. get: operationId: GetCustomerGroups summary: List Customer Groups description: Retrieve a list of customer groups. x-authenticated: true parameters: - in: query name: q description: Query used for searching customer group names. schema: type: string - in: query name: offset description: How many groups to skip in the result. schema: type: integer default: 0 - in: query name: order description: the field used to order the customer groups. schema: type: string - in: query name: discount_condition_id description: The discount condition id on which to filter the customer groups. schema: type: string - in: query name: id style: form explode: false description: Filter by the customer group ID schema: oneOf: - type: string description: customer group ID - type: array description: multiple customer group IDs items: type: string - type: object properties: lt: type: string description: filter by IDs less than this ID gt: type: string description: filter by IDs greater than this ID lte: type: string description: filter by IDs less than or equal to this ID gte: type: string description: filter by IDs greater than or equal to this ID - in: query name: name style: form explode: false description: Filter by the customer group name schema: type: array description: multiple customer group names items: type: string description: customer group name - in: query name: created_at description: Date comparison for when resulting customer groups were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting customer groups were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: limit description: Limit the number of customer groups returned. schema: type: integer default: 10 - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each customer groups of the result. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/customer-groups' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_groups: type: array items: $ref: '#/components/schemas/customer_group' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/customer-groups/{id}': delete: operationId: DeleteCustomerGroupsCustomerGroup summary: Delete a Customer Group description: Deletes a CustomerGroup. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Customer Group schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted customer group. object: type: string description: The type of the object that was deleted. default: customer_group deleted: type: boolean description: >- Whether the customer group was deleted successfully or not. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetCustomerGroupsGroup summary: Get a Customer Group description: Retrieves a Customer Group. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Customer Group. schema: type: string - in: query name: expand description: >- (Comma separated) Which fields should be expanded in the customer group. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in the customer group. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_group: $ref: '#/components/schemas/customer_group' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostCustomerGroupsGroup summary: Update a Customer Group description: Update a CustomerGroup. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the customer group. schema: type: string requestBody: content: application/json: schema: properties: name: description: Name of the customer group type: string metadata: description: Metadata for the customer. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.update(customer_group_id, { name: 'VIP' }) .then(({ customer_group }) => { console.log(customer_group.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "VIP" }' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customer_group: $ref: '#/components/schemas/customer_group' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/customer-groups/{id}/customers': get: operationId: GetCustomerGroupsGroupCustomers summary: List Customers description: Retrieves a list of customers in a customer group x-authenticated: true parameters: - in: path name: id required: true description: The ID of the customer group. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}/customers' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer Group responses: '200': description: OK content: application/json: schema: properties: customers: type: array items: $ref: '#/components/schemas/customer' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /customers: post: operationId: PostCustomers summary: Create a Customer description: Creates a Customer. x-authenticated: true requestBody: content: application/json: schema: required: - email - first_name - last_name - password properties: email: type: string description: The customer's email. format: email first_name: type: string description: The customer's first name. last_name: type: string description: The customer's last name. password: type: string description: The customer's password. format: password phone: type: string description: The customer's phone number. metadata: description: >- An optional set of key-value pairs to hold additional information. type: object tags: - Customer x-codeSamples: - lang: JavaScript label: JS Client source: > 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.create({ email: 'user@example.com', first_name: 'Caterina', last_name: 'Yost', password: 'supersecret' }) .then(({ customer }) => { console.log(customer.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/customers' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com", "first_name": "Caterina", "last_name": "Yost", "password": "supersecret" }' security: - api_token: [] - cookie_auth: [] responses: '201': description: OK content: application/json: schema: properties: customer: $ref: '#/components/schemas/customer' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetCustomers summary: List Customers description: Retrieves a list of Customers. x-authenticated: true parameters: - in: query name: limit description: The number of items to return. schema: type: integer default: 50 - in: query name: offset description: The items to skip before result. schema: type: integer default: 0 - in: query name: expand description: (Comma separated) Which fields should be expanded in each customer. schema: type: string - in: query name: q description: 'a search term to search email, first_name, and last_name.' schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/customers' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer responses: '200': description: OK content: application/json: schema: properties: customers: type: array items: $ref: '#/components/schemas/customer' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/customers/{id}': get: operationId: GetCustomersCustomer summary: Get a Customer description: Retrieves a Customer. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Customer. schema: type: string - in: query name: expand description: (Comma separated) Which fields should be expanded in the customer. schema: type: string - in: query name: fields description: (Comma separated) Which fields should be included in the customer. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/customers/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Customer responses: '200': description: OK content: application/json: schema: properties: customer: $ref: '#/components/schemas/customer' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostCustomersCustomer summary: Update a Customer description: Updates a Customer. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Customer. schema: type: string - in: query name: expand description: (Comma separated) Which fields should be expanded in each customer. schema: type: string - in: query name: fields description: (Comma separated) Which fields should be retrieved in each customer. schema: type: string requestBody: content: application/json: schema: properties: email: type: string description: The Customer's email. format: email first_name: type: string description: The Customer's first name. last_name: type: string description: The Customer's last name. phone: type: string description: The Customer's phone number. password: type: string description: The Customer's password. format: password groups: type: array items: required: - id properties: id: description: The ID of a customer group type: string description: A list of customer groups to which the customer belongs. metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.update(customer_id, { first_name: 'Dolly' }) .then(({ customer }) => { console.log(customer.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/customers/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Dolly" }' security: - api_token: [] - cookie_auth: [] tags: - Customer responses: '200': description: OK content: application/json: schema: properties: customer: $ref: '#/components/schemas/customer' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{id}/regions/{region_id}': post: operationId: PostDiscountsDiscountRegionsRegion summary: Add Region description: Adds a Region to the list of Regions that a Discount can be used in. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount. schema: type: string - in: path name: region_id required: true description: The ID of the Region. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.addRegion(discount_id, region_id) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteDiscountsDiscountRegionsRegion summary: Remove Region x-authenticated: true description: >- Removes a Region from the list of Regions that a Discount can be used in. parameters: - in: path name: id required: true description: The ID of the Discount. schema: type: string - in: path name: region_id required: true description: The ID of the Region. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.removeRegion(discount_id, region_id) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{discount_id}/conditions/{condition_id}/batch': post: operationId: PostDiscountsDiscountConditionsConditionBatch summary: Add a batch of resources to a discount condition description: Add a batch of resources to a discount condition. x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Product. schema: type: string - in: path name: condition_id required: true description: The ID of the condition on which to add the item. schema: type: string - in: query name: expand description: >- (Comma separated) Which relations should be expanded in each discount of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each discount of the result. schema: type: string requestBody: content: application/json: schema: required: - resources properties: resources: description: The resources to be added to the discount condition type: array items: required: - id properties: id: description: The id of the item type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.addConditionResourceBatch(discount_id, condition_id, { resources: [{ id: item_id }] }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "resources": [{ "id": "item_id" }] }' security: - api_token: [] - cookie_auth: [] tags: - Discount Condition responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteDiscountsDiscountConditionsConditionBatch summary: Delete a batch of resources from a discount condition description: Delete a batch of resources from a discount condition. x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Product. schema: type: string - in: path name: condition_id required: true description: The ID of the condition on which to add the item. schema: type: string - in: query name: expand description: >- (Comma separated) Which relations should be expanded in each discount of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each discount of the result. schema: type: string requestBody: content: application/json: schema: required: - resources properties: resources: description: The resources to be deleted from the discount condition type: array items: required: - id properties: id: description: The id of the item type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.deleteConditionResourceBatch(discount_id, condition_id, { resources: [{ id: item_id }] }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "resources": [{ "id": "item_id" }] }' security: - api_token: [] - cookie_auth: [] tags: - Discount Condition responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{discount_id}/conditions': post: operationId: PostDiscountsDiscountConditions summary: Create a Condition description: >- Creates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided. x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Product. schema: type: string - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each product of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each product of the result. schema: type: string requestBody: content: application/json: schema: required: - operator properties: operator: description: Operator of the condition type: string enum: - in - not_in products: type: array description: list of product IDs if the condition is applied on products. items: type: string product_types: type: array description: >- list of product type IDs if the condition is applied on product types. items: type: string product_collections: type: array description: >- list of product collection IDs if the condition is applied on product collections. items: type: string product_tags: type: array description: >- list of product tag IDs if the condition is applied on product tags. items: type: string customer_groups: type: array description: >- list of customer group IDs if the condition is applied on customer groups. items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > import Medusa from "@medusajs/medusa-js" import { DiscountConditionOperator } from "@medusajs/medusa" const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) // must be previously logged in or use api token medusa.admin.discounts.createCondition(discount_id, { operator: DiscountConditionOperator.IN }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "operator": "in" }' security: - api_token: [] - cookie_auth: [] tags: - Discount Condition responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /discounts: post: operationId: PostDiscounts summary: Creates a Discount x-authenticated: true description: >- Creates a Discount with a given set of rules that define how the Discount behaves. parameters: - in: query name: expand description: (Comma separated) Which fields should be expanded in each customer. schema: type: string - in: query name: fields description: (Comma separated) Which fields should be retrieved in each customer. schema: type: string requestBody: content: application/json: schema: required: - code - rule properties: code: type: string description: A unique code that will be used to redeem the Discount is_dynamic: type: boolean description: >- 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. default: false rule: description: The Discount Rule that defines how Discounts are calculated type: object required: - type - value - allocation properties: description: type: string description: A short description of the discount type: type: string description: >- The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. enum: - fixed - percentage - free_shipping value: type: number description: >- The value that the discount represents; this will depend on the type of the discount allocation: type: string description: The scope that the discount should apply to. enum: - total - item conditions: type: array description: >- A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided. items: type: object required: - operator properties: operator: type: string description: Operator of the condition enum: - in - not_in products: type: array description: >- list of product IDs if the condition is applied on products. items: type: string product_types: type: array description: >- list of product type IDs if the condition is applied on product types. items: type: string product_collections: type: array description: >- list of product collection IDs if the condition is applied on product collections. items: type: string product_tags: type: array description: >- list of product tag IDs if the condition is applied on product tags. items: type: string customer_groups: type: array description: >- list of customer group IDs if the condition is applied on customer groups. items: type: string is_disabled: type: boolean description: >- Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers. default: false starts_at: type: string format: date-time description: The time at which the Discount should be available. ends_at: type: string format: date-time description: >- The time at which the Discount should no longer be available. valid_duration: type: string description: Duration the discount runs between example: P3Y6M4DT12H30M5S regions: description: >- A list of Region ids representing the Regions in which the Discount can be used. type: array items: type: string usage_limit: type: number description: Maximum times the discount can be used metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > import Medusa from "@medusajs/medusa-js" import { AllocationType, DiscountRuleType } from "@medusajs/medusa" const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) // must be previously logged in or use api token medusa.admin.discounts.create({ code: 'TEST', rule: { type: DiscountRuleType.FIXED, value: 10, allocation: AllocationType.ITEM }, is_dynamic: false, is_disabled: false }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "TEST", "rule": { "type": "fixed", "value": 10, "allocation": "item" } }' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetDiscounts summary: List Discounts x-authenticated: true description: Retrieves a list of Discounts parameters: - in: query name: q description: Search query applied on the code field. schema: type: string - in: query name: rule description: Discount Rules filters to apply on the search schema: type: object properties: type: type: string enum: - fixed - percentage - free_shipping description: >- The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. allocation: type: string enum: - total - item description: >- The value that the discount represents; this will depend on the type of the discount - in: query name: is_dynamic description: Return only dynamic discounts. schema: type: boolean - in: query name: is_disabled description: Return only disabled discounts. schema: type: boolean - in: query name: limit description: The number of items in the response schema: type: number default: '20' - in: query name: offset description: The offset of items in response schema: type: number default: '0' - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/discounts' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discounts: type: array items: $ref: '#/components/schemas/discount' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{id}/dynamic-codes': post: operationId: PostDiscountsDiscountDynamicCodes summary: Create a Dynamic Code description: >- Creates a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same behaviour. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount to create the dynamic code from." schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.createDynamicCode(discount_id, { code: 'TEST', usage_limit: 1 }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "TEST" }' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' requestBody: content: application/json: schema: type: object required: - code properties: code: type: string description: The unique code that will be used to redeem the Discount. usage_limit: type: number default: '1' description: amount of times the discount can be applied. metadata: type: object description: >- An optional set of key-value paris to hold additional information. '/discounts/{discount_id}/conditions/{condition_id}': delete: operationId: DeleteDiscountsDiscountConditionsCondition summary: Delete a Condition description: Deletes a DiscountCondition x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Discount schema: type: string - in: path name: condition_id required: true description: The ID of the DiscountCondition schema: type: string - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.deleteCondition(discount_id, condition_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount Condition responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted DiscountCondition object: type: string description: The type of the object that was deleted. default: discount-condition deleted: type: boolean description: >- Whether the discount condition was deleted successfully or not. default: true discount: description: The Discount to which the condition used to belong $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetDiscountsDiscountConditionsCondition summary: Get a Condition description: Gets a DiscountCondition x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Discount. schema: type: string - in: path name: condition_id required: true description: The ID of the DiscountCondition. schema: type: string - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.getCondition(discount_id, condition_id) .then(({ discount_condition }) => { console.log(discount_condition.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount Condition responses: '200': description: OK content: application/json: schema: properties: discount_condition: $ref: '#/components/schemas/discount_condition' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostDiscountsDiscountConditionsCondition summary: Update a Condition description: >- Updates a DiscountCondition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided. x-authenticated: true parameters: - in: path name: discount_id required: true description: The ID of the Product. schema: type: string - in: path name: condition_id required: true description: The ID of the DiscountCondition. schema: type: string - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each item of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each item of the result. schema: type: string requestBody: content: application/json: schema: properties: products: type: array description: list of product IDs if the condition is applied on products. items: type: string product_types: type: array description: >- list of product type IDs if the condition is applied on product types. items: type: string product_collections: type: array description: >- list of product collection IDs if the condition is applied on product collections. items: type: string product_tags: type: array description: >- list of product tag IDs if the condition is applied on product tags. items: type: string customer_groups: type: array description: >- list of customer group IDs if the condition is applied on customer groups. items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.updateCondition(discount_id, condition_id, { products: [ product_id ] }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "products": [ "prod_01G1G5V2MBA328390B5AXJ610F" ] }' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{id}': delete: operationId: DeleteDiscountsDiscount summary: Delete a Discount description: Deletes a Discount. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.delete(discount_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Discount object: type: string description: The type of the object that was deleted. default: discount deleted: type: boolean description: Whether the discount was deleted successfully or not. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetDiscountsDiscount summary: Get a Discount description: Retrieves a Discount x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount schema: type: string - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.retrieve(discount_id) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostDiscountsDiscount summary: Update a Discount description: >- Updates a Discount with a given set of rules that define how the Discount behaves. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount. schema: type: string - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each item of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each item of the result. schema: type: string requestBody: content: application/json: schema: properties: code: type: string description: A unique code that will be used to redeem the Discount rule: description: The Discount Rule that defines how Discounts are calculated type: object required: - id properties: id: type: string description: The ID of the Rule description: type: string description: A short description of the discount value: type: number description: >- The value that the discount represents; this will depend on the type of the discount allocation: type: string description: The scope that the discount should apply to. enum: - total - item conditions: type: array description: >- A set of conditions that can be used to limit when the discount can be used. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided. items: type: object required: - operator properties: id: type: string description: The ID of the Rule operator: type: string description: Operator of the condition enum: - in - not_in products: type: array description: >- list of product IDs if the condition is applied on products. items: type: string product_types: type: array description: >- list of product type IDs if the condition is applied on product types. items: type: string product_collections: type: array description: >- list of product collection IDs if the condition is applied on product collections. items: type: string product_tags: type: array description: >- list of product tag IDs if the condition is applied on product tags. items: type: string customer_groups: type: array description: >- list of customer group IDs if the condition is applied on customer groups. items: type: string is_disabled: type: boolean description: >- Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers. starts_at: type: string format: date-time description: The time at which the Discount should be available. ends_at: type: string format: date-time description: >- The time at which the Discount should no longer be available. valid_duration: type: string description: Duration the discount runs between example: P3Y6M4DT12H30M5S usage_limit: type: number description: Maximum times the discount can be used regions: description: >- A list of Region ids representing the Regions in which the Discount can be used. type: array items: type: string metadata: description: An object containing metadata of the discount type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.update(discount_id, { code: 'TEST' }) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "TEST" }' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/{id}/dynamic-codes/{code}': delete: operationId: DeleteDiscountsDiscountDynamicCodesCode summary: Delete a Dynamic Code description: Deletes a dynamic code from a Discount. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Discount schema: type: string - in: path name: code required: true description: The ID of the Discount schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.deleteDynamicCode(discount_id, code) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/discounts/code/{code}': get: operationId: GetDiscountsDiscountCode summary: Get Discount by Code description: Retrieves a Discount by its discount code x-authenticated: true parameters: - in: path name: code required: true description: The code of the Discount schema: type: string - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.retrieveByCode(code) .then(({ discount }) => { console.log(discount.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/discounts/code/{code}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Discount responses: '200': description: OK content: application/json: schema: properties: discount: $ref: '#/components/schemas/discount' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /draft-orders: post: operationId: PostDraftOrders summary: Create a Draft Order description: Creates a Draft Order x-authenticated: true requestBody: content: application/json: schema: required: - email - items - region_id - shipping_methods properties: status: description: The status of the draft order type: string enum: - open - completed email: description: The email of the customer of the draft order type: string format: email billing_address: description: The Address to be used for billing purposes. anyOf: - $ref: '#/components/schemas/address_fields' - type: string shipping_address: description: The Address to be used for shipping. anyOf: - $ref: '#/components/schemas/address_fields' - type: string items: description: The Line Items that have been received. type: array items: type: object required: - quantity properties: variant_id: description: >- The ID of the Product Variant to generate the Line Item from. type: string unit_price: description: The potential custom price of the item. type: integer title: description: The potential custom title of the item. type: string quantity: description: The quantity of the Line Item. type: integer metadata: description: >- The optional key-value map with additional details about the Line Item. type: object region_id: description: The ID of the region for the draft order type: string discounts: description: The discounts to add on the draft order type: array items: type: object required: - code properties: code: description: The code of the discount to apply type: string customer_id: description: The ID of the customer to add on the draft order type: string no_notification_order: description: >- An optional flag passed to the resulting order to determine use of notifications. type: boolean shipping_methods: description: The shipping methods for the draft order type: array items: type: object required: - option_id properties: option_id: description: The ID of the shipping option in use type: string data: description: >- The optional additional data needed for the shipping method type: object price: description: The potential custom price of the shipping type: integer metadata: description: >- The optional key-value map with additional details about the Draft Order. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.create({ email: 'user@example.com', region_id, items: [ { quantity: 1 } ], shipping_methods: [ { option_id } ], }) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/draft-orders' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com", "region_id": "{region_id}" "items": [ { "quantity": 1 } ], "shipping_methods": [ { "option_id": "{option_id}" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetDraftOrders summary: List Draft Orders description: Retrieves an list of Draft Orders x-authenticated: true parameters: - in: query name: offset description: The number of items to skip before the results. schema: type: number default: '0' - in: query name: limit description: Limit the number of items returned. schema: type: number default: '50' - in: query name: q description: >- a search term to search emails in carts associated with draft orders and display IDs of draft orders schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.list() .then(({ draft_orders, limit, offset, count }) => { console.log(draft_orders.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/draft-orders' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_orders: type: array items: $ref: '#/components/schemas/draft-order' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/draft-orders/{id}/line-items': post: operationId: PostDraftOrdersDraftOrderLineItems summary: Create a Line Item description: Creates a Line Item for the Draft Order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string requestBody: content: application/json: schema: required: - quantity properties: variant_id: description: >- The ID of the Product Variant to generate the Line Item from. type: string unit_price: description: The potential custom price of the item. type: integer title: description: The potential custom title of the item. type: string default: Custom item quantity: description: The quantity of the Line Item. type: integer metadata: description: >- The optional key-value map with additional details about the Line Item. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.addLineItem(draft_order_id, { quantity: 1 }) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "quantity": 1 }' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/draft-orders/{id}': delete: operationId: DeleteDraftOrdersDraftOrder summary: Delete a Draft Order description: Deletes a Draft Order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.delete(draft_order_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Draft Order. object: type: string description: The type of the object that was deleted. default: draft-order deleted: type: boolean description: Whether the draft order was deleted successfully or not. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetDraftOrdersDraftOrder summary: Get a Draft Order description: Retrieves a Draft Order. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.retrieve(draft_order_id) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/draft-orders/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/draft-orders/{id}/line-items/{line_id}': delete: operationId: DeleteDraftOrdersDraftOrderLineItemsItem summary: Delete a Line Item description: Removes a Line Item from a Draft Order. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string - in: path name: line_id required: true description: The ID of the Draft Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.removeLineItem(draft_order_id, item_id) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostDraftOrdersDraftOrderLineItemsItem summary: Update a Line Item description: Updates a Line Item for a Draft Order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string - in: path name: line_id required: true description: The ID of the Line Item. schema: type: string requestBody: content: application/json: schema: properties: unit_price: description: The potential custom price of the item. type: integer title: description: The potential custom title of the item. type: string quantity: description: The quantity of the Line Item. type: integer metadata: description: >- The optional key-value map with additional details about the Line Item. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.updateLineItem(draft_order_id, line_id, { quantity: 1 }) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "quantity": 1 }' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/draft-orders/{id}/pay': post: summary: Registers a Payment operationId: PostDraftOrdersDraftOrderRegisterPayment description: Registers a payment for a Draft Order. x-authenticated: true parameters: - in: path name: id required: true description: The Draft Order id. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.markPaid(draft_order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/admin/draft-orders/{id}': post: operationId: PostDraftOrdersDraftOrder summary: Update a Draft Order description: Updates a Draft Order. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Draft Order. schema: type: string requestBody: content: application/json: schema: properties: region_id: type: string description: The ID of the Region to create the Draft Order in. country_code: type: string description: The 2 character ISO code for the Country. externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements description: See a list of codes. email: type: string description: An email to be used on the Draft Order. format: email billing_address: description: The Address to be used for billing purposes. anyOf: - $ref: '#/components/schemas/address_fields' - type: string shipping_address: description: The Address to be used for shipping. anyOf: - $ref: '#/components/schemas/address_fields' - type: string discounts: description: An array of Discount codes to add to the Draft Order. type: array items: type: object required: - code properties: code: description: The code that a Discount is identifed by. type: string no_notification_order: description: >- An optional flag passed to the resulting order to determine use of notifications. type: boolean customer_id: description: The ID of the Customer to associate the Draft Order with. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.draftOrders.update(draft_order_id, { email: "user@example.com" }) .then(({ draft_order }) => { console.log(draft_order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com" }' security: - api_token: [] - cookie_auth: [] tags: - Draft Order responses: '200': description: OK content: application/json: schema: properties: draft_order: $ref: '#/components/schemas/draft-order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /gift-cards: post: operationId: PostGiftCards summary: Create a Gift Card description: >- Creates a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region. x-authenticated: true requestBody: content: application/json: schema: required: - region_id properties: value: type: integer description: >- The value (excluding VAT) that the Gift Card should represent. is_disabled: type: boolean description: >- Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers. ends_at: type: string format: date-time description: >- The time at which the Gift Card should no longer be available. region_id: description: The ID of the Region in which the Gift Card can be used. type: string metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.giftCards.create({ region_id }) .then(({ gift_card }) => { console.log(gift_card.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/gift-cards' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "region_id": "{region_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Gift Card responses: '200': description: OK content: application/json: schema: properties: gift_card: $ref: '#/components/schemas/gift_card' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetGiftCards summary: List Gift Cards description: Retrieves a list of Gift Cards. x-authenticated: true parameters: - in: query name: offset description: The number of items to skip before the results. schema: type: number default: '0' - in: query name: limit description: Limit the number of items returned. schema: type: number default: '50' - in: query name: q description: a search term to search by code or display ID schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.giftCards.list() .then(({ gift_cards, limit, offset, count }) => { console.log(gift_cards.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/gift-cards' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Gift Card responses: '200': description: OK content: application/json: schema: properties: gift_cards: type: array items: $ref: '#/components/schemas/gift_card' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/gift-cards/{id}': delete: operationId: DeleteGiftCardsGiftCard summary: Delete a Gift Card description: Deletes a Gift Card x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Gift Card to delete. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.giftCards.delete(gift_card_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Gift Card responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Gift Card object: type: string description: The type of the object that was deleted. default: gift-card deleted: type: boolean description: Whether the gift card was deleted successfully or not. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetGiftCardsGiftCard summary: Get a Gift Card description: Retrieves a Gift Card. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Gift Card. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.giftCards.retrieve(gift_card_id) .then(({ gift_card }) => { console.log(gift_card.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/gift-cards/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Gift Card responses: '200': description: OK content: application/json: schema: properties: gift_card: $ref: '#/components/schemas/gift_card' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostGiftCardsGiftCard summary: Update a Gift Card description: >- Update a Gift Card that can redeemed by its unique code. The Gift Card is only valid within 1 region. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Gift Card. schema: type: string requestBody: content: application/json: schema: properties: balance: type: integer description: >- The value (excluding VAT) that the Gift Card should represent. is_disabled: type: boolean description: >- Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers. ends_at: type: string format: date-time description: >- The time at which the Gift Card should no longer be available. region_id: description: The ID of the Region in which the Gift Card can be used. type: string metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.giftCards.update(gift_card_id, { region_id }) .then(({ gift_card }) => { console.log(gift_card.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/gift-cards/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "region_id": "{region_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Gift Card responses: '200': description: OK content: application/json: schema: properties: gift_card: $ref: '#/components/schemas/gift_card' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /invites/accept: post: operationId: PostInvitesInviteAccept summary: Accept an Invite description: Accepts an Invite and creates a corresponding user requestBody: content: application/json: schema: required: - token - user properties: token: description: The invite token provided by the admin. type: string user: description: The User to create. type: object required: - first_name - last_name - password properties: first_name: type: string description: the first name of the User last_name: type: string description: the last name of the User password: description: The desired password for the User type: string format: password x-codeSamples: - lang: JavaScript label: JS Client source: > 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.invites.accept({ token, user: { first_name: 'Brigitte', last_name: 'Collier', password: 'supersecret' } }) .then(() => { // successful }) .catch(() => { // an error occurred }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/invites/accept' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "token": "{token}", "user": { "first_name": "Brigitte", "last_name": "Collier", "password": "supersecret" } }' security: - api_token: [] - cookie_auth: [] tags: - Invite responses: '200': description: OK '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /invites: post: operationId: PostInvites summary: Create an Invite description: Creates an Invite and triggers an 'invite' created event x-authenticated: true requestBody: content: application/json: schema: required: - user - role properties: user: description: The email for the user to be created. type: string format: email role: description: The role of the user to be created. type: string enum: - admin - member - developer x-codeSamples: - lang: JavaScript label: JS Client source: > 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.invites.create({ user: "user@example.com", role: "admin" }) .then(() => { // successful }) .catch(() => { // an error occurred }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/invites' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "user": "user@example.com", "role": "admin" }' security: - api_token: [] - cookie_auth: [] tags: - Invite responses: '200': description: OK '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetInvites summary: Lists Invites description: Lists all Invites x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.invites.list() .then(({ invites }) => { console.log(invites.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/invites' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Invite responses: '200': description: OK content: application/json: schema: properties: invites: type: array items: $ref: '#/components/schemas/invite' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/invites/{invite_id}': delete: operationId: DeleteInvitesInvite summary: Create an Invite description: Creates an Invite and triggers an 'invite' created event x-authenticated: true parameters: - in: path name: invite_id required: true description: The ID of the Invite schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.invites.delete(invite_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Invite responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Invite. object: type: string description: The type of the object that was deleted. format: invite deleted: type: boolean description: Whether or not the Invite was deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/invites/{invite_id}/resend': post: operationId: PostInvitesInviteResend summary: Resend an Invite description: Resends an Invite by triggering the 'invite' created event again x-authenticated: true parameters: - in: path name: invite_id required: true description: The ID of the Invite schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.invites.resend(invite_id) .then(() => { // successful }) .catch(() => { // an error occurred }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Invite responses: '200': description: OK '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /notes: post: operationId: PostNotes summary: Creates a Note description: Creates a Note which can be associated with any resource as required. x-authenticated: true requestBody: content: application/json: schema: required: - resource_id - resource_type - value properties: resource_id: type: string description: The ID of the resource which the Note relates to. resource_type: type: string description: The type of resource which the Note relates to. value: type: string description: The content of the Note to create. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notes.create({ resource_id, resource_type: 'order', value: 'We delivered this order' }) .then(({ note }) => { console.log(note.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/notes' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "resource_id": "{resource_id}", "resource_type": "order", "value": "We delivered this order" }' security: - api_token: [] - cookie_auth: [] tags: - Note responses: '200': description: OK content: application/json: schema: properties: note: $ref: '#/components/schemas/note' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetNotes summary: List Notes x-authenticated: true description: Retrieves a list of notes parameters: - in: query name: limit description: The number of notes to get schema: type: number default: '50' - in: query name: offset description: The offset at which to get notes schema: type: number default: '0' - in: query name: resource_id description: The ID which the notes belongs to schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notes.list() .then(({ notes, limit, offset, count }) => { console.log(notes.length); }); - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/notes' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Note responses: '200': description: OK content: application/json: schema: properties: notes: type: array items: $ref: '#/components/schemas/note' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/notes/{id}': delete: operationId: DeleteNotesNote summary: Delete a Note description: Deletes a Note. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Note to delete. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notes.delete(note_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/notes/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Note responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Note. object: type: string description: The type of the object that was deleted. default: note deleted: type: boolean description: Whether or not the Note was deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetNotesNote summary: Get a Note description: Retrieves a single note using its id x-authenticated: true parameters: - in: path name: id required: true description: The ID of the note to retrieve. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notes.retrieve(note_id) .then(({ note }) => { console.log(note.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/notes/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Note responses: '200': description: OK content: application/json: schema: properties: note: $ref: '#/components/schemas/note' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostNotesNote summary: Update a Note x-authenticated: true description: Updates a Note associated with some resource parameters: - in: path name: id required: true description: The ID of the Note to update schema: type: string requestBody: content: application/json: schema: required: - value properties: value: type: string description: The updated description of the Note. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notes.update(note_id, { value: 'We delivered this order' }) .then(({ note }) => { console.log(note.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/notes/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "value": "We delivered this order" }' security: - api_token: [] - cookie_auth: [] tags: - Note responses: '200': description: OK content: application/json: schema: properties: note: $ref: '#/components/schemas/note' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /notifications: get: operationId: GetNotifications summary: List Notifications description: Retrieves a list of Notifications. x-authenticated: true parameters: - in: query name: offset description: >- The number of notifications to skip before starting to collect the notifications set schema: type: integer default: 0 - in: query name: limit description: The number of notifications to return schema: type: integer default: 50 - in: query name: fields description: Comma separated fields to include in the result set schema: type: string - in: query name: expand description: Comma separated fields to populate schema: type: string - in: query name: event_name description: The name of the event that the notification was sent for. schema: type: string - in: query name: resource_type description: The type of resource that the Notification refers to. schema: type: string - in: query name: resource_id description: The ID of the resource that the Notification refers to. schema: type: string - in: query name: to description: >- The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id schema: type: string - in: query name: include_resends description: >- A boolean indicating whether the result set should include resent notifications or not schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notifications.list() .then(({ notifications }) => { console.log(notifications.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/notifications' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Notification responses: '200': description: OK content: application/json: schema: properties: notifications: type: array items: $ref: '#/components/schemas/notification' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/notifications/{id}/resend': post: operationId: PostNotificationsNotificationResend summary: Resend Notification description: >- Resends a previously sent notifications, with the same data but optionally to a different address x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Notification schema: type: string requestBody: content: application/json: schema: properties: to: description: >- A new address or user identifier that the Notification should be sent to type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.notifications.resend(notification_id) .then(({ notification }) => { console.log(notification.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/notifications/{id}/resend' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Notification responses: '200': description: OK content: application/json: schema: properties: notification: $ref: '#/components/schemas/notification' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/items': post: operationId: PostOrderEditsEditLineItems summary: Add an line item to an order (edit) description: Create an OrderEdit LineItem. parameters: - in: path name: id required: true description: The ID of the Order Edit. schema: type: string requestBody: content: application/json: schema: required: - variant_id - quantity properties: variant_id: description: The ID of the variant ID to add type: string quantity: description: The quantity to add type: number metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.addLineItem(order_edit_id, { variant_id, quantity }) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/cancel': post: operationId: PostOrderEditsOrderEditCancel summary: Cancel an OrderEdit description: Cancels an OrderEdit. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the OrderEdit. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.cancel(order_edit_id) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/confirm': post: operationId: PostOrderEditsOrderEditConfirm summary: Confirms an OrderEdit description: Confirms an OrderEdit. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the order edit. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.confirm(order_edit_id) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/confirm' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '500': $ref: '#/components/responses/500_error' /order-edits: post: operationId: PostOrderEdits summary: Create an OrderEdit description: Creates an OrderEdit. requestBody: content: application/json: schema: required: - order_id properties: order_id: description: The ID of the order to create the edit for. type: string internal_note: description: An optional note to create for the order edit. type: string x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.create({ order_id }) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "order_id": "my_order_id", "internal_note": "my_optional_note" }' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetOrderEdits summary: List an OrderEdit description: List a OrderEdit. x-authenticated: true parameters: - in: query name: q description: Query used for searching order edit internal note. schema: type: string - in: query name: order_id description: List order edits by order id. schema: type: string - in: query name: limit description: The number of items in the response schema: type: number default: '20' - in: query name: offset description: The offset of items in response schema: type: number default: '0' - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.list() .then(({ order_edits, count, limit, offset }) => { console.log(order_edits.length) }) - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/order-edits' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edits: type: array $ref: '#/components/schemas/order_edit' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/items/{item_id}': delete: operationId: DeleteOrderEditsOrderEditLineItemsLineItem summary: Delete line items from an order edit and create change item description: Delete line items from an order edit and create change item x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order Edit to delete from. schema: type: string - in: path name: item_id required: true description: The ID of the order edit item to delete from order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.removeLineItem(order_edit_id, line_item_id) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostOrderEditsEditLineItemsLineItem summary: Create or update the order edit change holding the line item changes description: Create or update the order edit change holding the line item changes x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order Edit to update. schema: type: string - in: path name: item_id required: true description: The ID of the order edit item to update. schema: type: string requestBody: content: application/json: schema: required: - quantity properties: quantity: description: The quantity to update type: number x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.updateLineItem(order_edit_id, line_item_id, { quantity: 5 }) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/items/{item_id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "quantity": 5 }' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/changes/{change_id}': delete: operationId: DeleteOrderEditsOrderEditItemChange summary: Delete an Order Edit Item Change description: Deletes an Order Edit Item Change x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order Edit to delete. schema: type: string - in: path name: change_id required: true description: The ID of the Order Edit Item Change to delete. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.deleteItemChange(order_edit_id, item_change_id) .then(({ id, object, deleted }) => { console.log(id) }) - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}/changes/{change_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Order Edit Item Change. object: type: string description: The type of the object that was deleted. format: item_change deleted: type: boolean description: Whether or not the Order Edit Item Change was deleted. default: true '400': $ref: '#/components/responses/400_error' '/order-edits/{id}': delete: operationId: DeleteOrderEditsOrderEdit summary: Delete an Order Edit description: Deletes an Order Edit x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order Edit to delete. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.delete(order_edit_id) .then(({ id, object, deleted }) => { console.log(id) }) - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/order-edits/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Order Edit. object: type: string description: The type of the object that was deleted. format: order_edit deleted: type: boolean description: Whether or not the Order Edit was deleted. default: true '400': $ref: '#/components/responses/400_error' get: operationId: GetOrderEditsOrderEdit summary: Retrieve an OrderEdit description: Retrieves a OrderEdit. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the OrderEdit. schema: type: string - in: query name: expand description: Comma separated list of relations to include in the results. schema: type: string - in: query name: fields description: Comma separated list of fields to include in the results. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.retrieve(orderEditId) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/order-edits/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostOrderEditsOrderEdit summary: Updates an OrderEdit description: Updates a OrderEdit. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the OrderEdit. schema: type: string requestBody: content: application/json: schema: properties: internal_note: description: An optional note to create or update for the order edit. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.update(order_edit_id, { internal_note: "internal reason XY" }) .then(({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "internal_note": "internal reason XY" }' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order-edits/{id}/request': post: operationId: PostOrderEditsOrderEditRequest summary: Request order edit confirmation description: Request customer confirmation of an Order Edit x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order Edit to request confirmation from. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orderEdits.requestConfirmation(order_edit_id) .then({ order_edit }) => { console.log(order_edit.id) }) - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/order-edits/{id}/request' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - OrderEdit responses: '200': description: OK content: application/json: schema: properties: order_edit: $ref: '#/components/schemas/order_edit' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/shipping-methods': post: operationId: PostOrdersOrderShippingMethods summary: Add a Shipping Method description: >- Adds a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.addShippingMethod(order_id, { price: 1000, option_id }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "price": 1000, "option_id": "{option_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' requestBody: content: application/json: schema: type: object required: - price - option_id properties: price: type: integer description: >- The price (excluding VAT) that should be charged for the Shipping Method option_id: type: string description: >- The ID of the Shipping Option to create the Shipping Method from. data: type: object description: >- The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider. '/orders/{id}/archive': post: operationId: PostOrdersOrderArchive summary: Archive Order description: Archives the order with the given id. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.archive(order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/archive' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/claims/{claim_id}/cancel': post: operationId: PostOrdersClaimCancel summary: Cancel a Claim description: Cancels a Claim x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: claim_id required: true description: The ID of the Claim. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancelClaim(order_id, claim_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Claim responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel': post: operationId: PostOrdersClaimFulfillmentsCancel summary: Cancel Claim Fulfillment description: Registers a claim's fulfillment as canceled. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order which the Claim relates to. schema: type: string - in: path name: claim_id required: true description: The ID of the Claim which the Fulfillment relates to. schema: type: string - in: path name: fulfillment_id required: true description: The ID of the Fulfillment. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancelClaimFulfillment(order_id, claim_id, fulfillment_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel': post: operationId: PostOrdersSwapFulfillmentsCancel summary: Cancel Swap's Fulfilmment description: Registers a Swap's Fulfillment as canceled. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order which the Swap relates to. schema: type: string - in: path name: swap_id required: true description: The ID of the Swap which the Fulfillment relates to. schema: type: string - in: path name: fulfillment_id required: true description: The ID of the Fulfillment. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancelSwapFulfillment(order_id, swap_id, fulfillment_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/fulfillments/{fulfillment_id}/cancel': post: operationId: PostOrdersOrderFulfillmentsCancel summary: Cancels a Fulfilmment description: Registers a Fulfillment as canceled. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order which the Fulfillment relates to. schema: type: string - in: path name: fulfillment_id required: true description: The ID of the Fulfillment schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancelFulfillment(order_id, fulfillment_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/cancel': post: operationId: PostOrdersOrderCancel summary: Cancel an Order description: >- Registers an Order as canceled. This triggers a flow that will cancel any created Fulfillments and Payments, may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancel(order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/swaps/{swap_id}/cancel': post: operationId: PostOrdersSwapCancel summary: Cancels a Swap description: Cancels a Swap x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: swap_id required: true description: The ID of the Swap. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.cancelSwap(order_id, swap_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/capture': post: operationId: PostOrdersOrderCapture summary: Capture Order's Payment description: Captures all the Payments associated with an Order. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.capturePayment(order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/capture' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/complete': post: operationId: PostOrdersOrderComplete summary: Complete an Order description: Completes an Order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.complete(order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/complete' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/claims/{claim_id}/shipments': post: operationId: PostOrdersOrderClaimsClaimShipments summary: Create Claim Shipment description: Registers a Claim Fulfillment as shipped. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: claim_id required: true description: The ID of the Claim. schema: type: string requestBody: content: application/json: schema: required: - fulfillment_id properties: fulfillment_id: description: The ID of the Fulfillment. type: string tracking_numbers: description: The tracking numbers for the shipment. type: array items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createClaimShipment(order_id, claim_id, { fulfillment_id }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "fulfillment_id": "{fulfillment_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Claim responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order/{id}/claims': post: operationId: PostOrdersOrderClaims summary: Create a Claim description: Creates a Claim. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - type - claim_items properties: type: description: >- The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items. type: string enum: - replace - refund claim_items: description: The Claim Items that the Claim will consist of. type: array items: required: - item_id - quantity properties: item_id: description: The ID of the Line Item that will be claimed. type: string quantity: description: The number of items that will be returned type: integer note: description: >- Short text describing the Claim Item in further detail. type: string reason: description: The reason for the Claim type: string enum: - missing_item - wrong_item - production_failure - other tags: description: A list o tags to add to the Claim Item type: array items: type: string images: description: >- A list of image URL's that will be associated with the Claim items: type: string return_shipping: description: >- Optional details for the Return Shipping Method, if the items are to be sent back. type: object properties: option_id: type: string description: >- The ID of the Shipping Option to create the Shipping Method from. price: type: integer description: The price to charge for the Shipping Method. additional_items: description: >- The new items to send to the Customer when the Claim type is Replace. type: array items: required: - variant_id - quantity properties: variant_id: description: The ID of the Product Variant to ship. type: string quantity: description: The quantity of the Product Variant to ship. type: integer shipping_methods: description: The Shipping Methods to send the additional Line Items with. type: array items: properties: id: description: The ID of an existing Shipping Method type: string option_id: description: >- The ID of the Shipping Option to create a Shipping Method from type: string price: description: The price to charge for the Shipping Method type: integer shipping_address: type: object description: >- An optional shipping address to send the claim to. Defaults to the parent order's shipping address $ref: '#/components/schemas/address' refund_amount: description: >- The amount to refund the Customer when the Claim type is `refund`. type: integer no_notification: description: >- If set to true no notification will be send related to this Claim. type: boolean metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createClaim(order_id, { type: 'refund', claim_items: [ { item_id, quantity: 1 } ] }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "refund", "claim_items": [ { "item_id": "asdsd", "quantity": 1 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Claim responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/fulfillment': post: operationId: PostOrdersOrderFulfillments summary: Create a Fulfillment description: >- Creates a Fulfillment of an Order - will notify Fulfillment Providers to prepare a shipment. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - items properties: items: description: The Line Items to include in the Fulfillment. type: array items: required: - item_id - quantity properties: item_id: description: The ID of Line Item to fulfill. type: string quantity: description: The quantity of the Line Item to fulfill. type: integer no_notification: description: >- If set to true no notification will be send related to this Swap. type: boolean metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createFulfillment(order_id, { items: [ { item_id, quantity: 1 } ] }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "items": [ { "item_id": "{item_id}", "quantity": 1 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/shipment': post: operationId: PostOrdersOrderShipment summary: Create a Shipment description: Registers a Fulfillment as shipped. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - fulfillment_id properties: fulfillment_id: description: The ID of the Fulfillment. type: string tracking_numbers: description: The tracking numbers for the shipment. type: array items: type: string no_notification: description: >- If set to true no notification will be send related to this Shipment. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createShipment(order_id, { fulfillment_id }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipment' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "fulfillment_id": "{fulfillment_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/swaps/{swap_id}/shipments': post: operationId: PostOrdersOrderSwapsSwapShipments summary: Create Swap Shipment description: Registers a Swap Fulfillment as shipped. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: swap_id required: true description: The ID of the Swap. schema: type: string requestBody: content: application/json: schema: required: - fulfillment_id properties: fulfillment_id: description: The ID of the Fulfillment. type: string tracking_numbers: description: The tracking numbers for the shipment. type: array items: type: string no_notification: description: >- If set to true no notification will be sent related to this Claim. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createSwapShipment(order_id, swap_id, { fulfillment_id }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "fulfillment_id": "{fulfillment_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order/{id}/swaps': post: operationId: PostOrdersOrderSwaps summary: Create a Swap description: >- Creates a Swap. Swaps are used to handle Return of previously purchased goods and Fulfillment of replacements simultaneously. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - return_items properties: return_items: description: The Line Items to return as part of the Swap. type: array items: required: - item_id - quantity properties: item_id: description: The ID of the Line Item that will be claimed. type: string quantity: description: The number of items that will be returned type: integer reason_id: description: The ID of the Return Reason to use. type: string note: description: An optional note with information about the Return. type: string return_shipping: description: How the Swap will be returned. type: object required: - option_id properties: option_id: type: string description: >- The ID of the Shipping Option to create the Shipping Method from. price: type: integer description: The price to charge for the Shipping Method. additional_items: description: The new items to send to the Customer. type: array items: required: - variant_id - quantity properties: variant_id: description: The ID of the Product Variant to ship. type: string quantity: description: The quantity of the Product Variant to ship. type: integer custom_shipping_options: description: >- The custom shipping options to potentially create a Shipping Method from. type: array items: required: - option_id - price properties: option_id: description: >- The ID of the Shipping Option to override with a custom price. type: string price: description: The custom price of the Shipping Option. type: integer no_notification: description: >- If set to true no notification will be send related to this Swap. type: boolean allow_backorder: description: 'If true, swaps can be completed with items out of stock' type: boolean default: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.createSwap(order_id, { return_items: [ { item_id, quantity: 1 } ] }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "return_items": [ { "item_id": "asfasf", "quantity": 1 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/claims/{claim_id}/fulfillments': post: operationId: PostOrdersOrderClaimsClaimFulfillments summary: Create Claim Fulfillment description: Creates a Fulfillment for a Claim. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: claim_id required: true description: The ID of the Claim. schema: type: string requestBody: content: application/json: schema: properties: metadata: description: >- An optional set of key-value pairs to hold additional information. type: object no_notification: description: >- If set to true no notification will be send related to this Claim. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.fulfillClaim(order_id, claim_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/swaps/{swap_id}/fulfillments': post: operationId: PostOrdersOrderSwapsSwapFulfillments summary: Create Swap Fulfillment description: Creates a Fulfillment for a Swap. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: swap_id required: true description: The ID of the Swap. schema: type: string requestBody: content: application/json: schema: properties: metadata: description: >- An optional set of key-value pairs to hold additional information. type: object no_notification: description: >- If set to true no notification will be send related to this Claim. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.fulfillSwap(order_id, swap_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Fulfillment responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}': get: operationId: GetOrdersOrder summary: Get an Order description: Retrieves an Order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.retrieve(order_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/orders/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostOrdersOrder summary: Update an Order description: Updates and order x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: properties: email: description: the email for the order type: string billing_address: description: Billing address anyOf: - $ref: '#/components/schemas/address_fields' shipping_address: description: Shipping address anyOf: - $ref: '#/components/schemas/address_fields' items: description: The Line Items for the order type: array items: $ref: '#/components/schemas/line_item' region: description: ID of the region where the order belongs type: string discounts: description: Discounts applied to the order type: array items: $ref: '#/components/schemas/discount' customer_id: description: ID of the customer type: string payment_method: description: payment method chosen for the order type: object properties: provider_id: type: string description: ID of the payment provider data: description: Data relevant for the given payment method type: object shipping_method: description: The Shipping Method used for shipping the order. type: object properties: provider_id: type: string description: The ID of the shipping provider. profile_id: type: string description: The ID of the shipping profile. price: type: integer description: The price of the shipping. data: type: object description: Data relevant to the specific shipping method. items: type: array items: $ref: '#/components/schemas/line_item' description: Items to ship no_notification: description: >- A flag to indicate if no notifications should be emitted related to the updated order. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.update(order_id, { email: 'user@example.com' }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/adasda' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com" }' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /orders: get: operationId: GetOrders summary: List Orders description: Retrieves a list of Orders x-authenticated: true parameters: - in: query name: q description: >- Query used for searching orders by shipping address first name, orders' email, and orders' display ID schema: type: string - in: query name: id description: ID of the order to search for. schema: type: string - in: query name: status style: form explode: false description: Status to search for schema: type: array items: type: string enum: - pending - completed - archived - canceled - requires_action - in: query name: fulfillment_status style: form explode: false description: Fulfillment status to search for. schema: type: array items: type: string enum: - not_fulfilled - fulfilled - partially_fulfilled - shipped - partially_shipped - canceled - returned - partially_returned - requires_action - in: query name: payment_status style: form explode: false description: Payment status to search for. schema: type: array items: type: string enum: - captured - awaiting - not_paid - refunded - partially_refunded - canceled - requires_action - in: query name: display_id description: Display ID to search for. schema: type: string - in: query name: cart_id description: to search for. schema: type: string - in: query name: customer_id description: to search for. schema: type: string - in: query name: email description: to search for. schema: type: string - in: query name: region_id style: form explode: false description: Regions to search orders by schema: oneOf: - type: string description: ID of a Region. - type: array items: type: string description: ID of a Region. - in: query name: currency_code style: form explode: false description: Currency code to search for schema: type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. - in: query name: tax_rate description: to search for. schema: type: string - in: query name: created_at description: Date comparison for when resulting orders were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting orders were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: canceled_at description: Date comparison for when resulting orders were canceled. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: sales_channel_id style: form explode: false description: Filter by Sales Channels schema: type: array items: type: string description: The ID of a Sales Channel - in: query name: offset description: How many orders to skip before the results. schema: type: integer default: 0 - in: query name: limit description: Limit the number of orders returned. schema: type: integer default: 50 - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each order of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each order of the result. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.list() .then(({ orders, limit, offset, count }) => { console.log(orders.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/orders' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: orders: type: array items: $ref: '#/components/schemas/order' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/swaps/{swap_id}/process-payment': post: operationId: PostOrdersOrderSwapsSwapProcessPayment summary: Process Swap Payment description: >- When there are differences between the returned and shipped Products in a Swap, the difference must be processed. Either a Refund will be issued or a Payment will be captured. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: swap_id required: true description: The ID of the Swap. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.processSwapPayment(order_id, swap_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/refund': post: operationId: PostOrdersOrderRefunds summary: Create a Refund description: Issues a Refund. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - amount - reason properties: amount: description: The amount to refund. type: integer reason: description: The reason for the Refund. type: string note: description: A note with additional details about the Refund. type: string no_notification: description: >- If set to true no notification will be send related to this Refund. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.refundPayment(order_id, { amount: 1000, reason: 'Do not like it' }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/adasda/refund' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 1000, "reason": "Do not like it" }' security: - api_token: [] - cookie_auth: [] tags: - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/orders/{id}/return': post: operationId: PostOrdersOrderReturns summary: Request a Return description: >- Requests a Return. If applicable a return label will be created and other plugins notified. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string requestBody: content: application/json: schema: required: - items properties: items: description: The Line Items that will be returned. type: array items: required: - item_id - quantity properties: item_id: description: The ID of the Line Item. type: string reason_id: description: The ID of the Return Reason to use. type: string note: description: An optional note with information about the Return. type: string quantity: description: The quantity of the Line Item. type: integer return_shipping: description: >- The Shipping Method to be used to handle the return shipment. type: object properties: option_id: type: string description: >- The ID of the Shipping Option to create the Shipping Method from. price: type: integer description: The price to charge for the Shipping Method. note: description: An optional note with information about the Return. type: string receive_now: description: >- A flag to indicate if the Return should be registerd as received immediately. type: boolean default: false no_notification: description: >- A flag to indicate if no notifications should be emitted related to the requested Return. type: boolean refund: description: The amount to refund. type: integer x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.requestReturn(order_id, { items: [ { item_id, quantity: 1 } ] }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/return' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "items": [ { "item_id": "{item_id}", "quantity": 1 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Return - Order responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/order/{id}/claims/{claim_id}': post: operationId: PostOrdersOrderClaimsClaim summary: Update a Claim description: Updates a Claim. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Order. schema: type: string - in: path name: claim_id required: true description: The ID of the Claim. schema: type: string requestBody: content: application/json: schema: properties: claim_items: description: The Claim Items that the Claim will consist of. type: array items: required: - id - images - tags properties: id: description: The ID of the Claim Item. type: string item_id: description: The ID of the Line Item that will be claimed. type: string quantity: description: The number of items that will be returned type: integer note: description: >- Short text describing the Claim Item in further detail. type: string reason: description: The reason for the Claim type: string enum: - missing_item - wrong_item - production_failure - other tags: description: A list o tags to add to the Claim Item type: array items: type: object properties: id: type: string description: Tag ID value: type: string description: Tag value images: description: >- A list of image URL's that will be associated with the Claim type: array items: type: object properties: id: type: string description: Image ID url: type: string description: Image URL metadata: description: >- An optional set of key-value pairs to hold additional information. type: object shipping_methods: description: The Shipping Methods to send the additional Line Items with. type: array items: properties: id: description: The ID of an existing Shipping Method type: string option_id: description: >- The ID of the Shipping Option to create a Shipping Method from type: string price: description: The price to charge for the Shipping Method type: integer no_notification: description: >- If set to true no notification will be send related to this Swap. type: boolean metadata: description: >- An optional set of key-value pairs to hold additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.orders.updateClaim(order_id, claim_id, { no_notification: true }) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "no_notification": true }' security: - api_token: [] - cookie_auth: [] tags: - Claim responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/price-lists/{id}/prices/batch': post: operationId: PostPriceListsPriceListPricesBatch summary: Update Prices description: Batch update prices for a Price List x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Price List to update prices for. schema: type: string requestBody: content: application/json: schema: properties: prices: description: The prices to update or add. type: array items: required: - amount - variant_id properties: id: description: The ID of the price. type: string region_id: description: >- The ID of the Region for which the price is used. Only required if currecny_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. variant_id: description: The ID of the Variant for which the price is used. type: string amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: The minimum quantity for which the price will be used. type: integer max_quantity: description: The maximum quantity for which the price will be used. type: integer override: description: >- If true the prices will replace all existing prices associated with the Price List. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.addPrices(price_list_id, { prices: [ { amount: 1000, variant_id, currency_code: 'eur' } ] }) .then(({ price_list }) => { console.log(price_list.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "prices": [ { "amount": 100, "variant_id": "afasfa", "currency_code": "eur" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: price_list: $ref: '#/components/schemas/price_list' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeletePriceListsPriceListPricesBatch summary: Delete Prices description: Batch delete prices that belong to a Price List x-authenticated: true parameters: - in: path name: id required: true description: >- The ID of the Price List that the Money Amounts (Prices) that will be deleted belongs to. schema: type: string requestBody: content: application/json: schema: properties: price_ids: description: The price id's of the Money Amounts to delete. type: array items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.deletePrices(price_list_id, { price_ids: [ price_id ] }) .then(({ ids, object, deleted }) => { console.log(ids.length); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/prices/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_ids": [ "adasfa" ] }' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: ids: type: array items: type: string description: The IDs of the deleted Money Amounts (Prices). object: type: string description: The type of the object that was deleted. default: money-amount deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /price-lists: post: operationId: PostPriceListsPriceList summary: Create a Price List description: Creates a Price List x-authenticated: true requestBody: content: application/json: schema: required: - name - description - type - prices properties: name: description: The name of the Price List type: string description: description: A description of the Price List. type: string starts_at: description: >- The date with timezone that the Price List starts being valid. type: string format: date ends_at: description: The date with timezone that the Price List ends being valid. type: string format: date type: description: The type of the Price List. type: string enum: - sale - override status: description: The status of the Price List. type: string enum: - active - draft prices: description: The prices of the Price List. type: array items: required: - amount - variant_id properties: region_id: description: >- The ID of the Region for which the price is used. Only required if currecny_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. amount: description: The amount to charge for the Product Variant. type: integer variant_id: description: The ID of the Variant for which the price is used. type: string min_quantity: description: The minimum quantity for which the price will be used. type: integer max_quantity: description: The maximum quantity for which the price will be used. type: integer customer_groups: type: array description: A list of customer groups that the Price List applies to. items: required: - id properties: id: description: The ID of a customer group type: string includes_tax: description: '[EXPERIMENTAL] Tax included in prices of price list' type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > import Medusa from "@medusajs/medusa-js" import { PriceListType } from "@medusajs/medusa" const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 }) // must be previously logged in or use api token medusa.admin.priceLists.create({ name: 'New Price List', description: 'A new price list', type: PriceListType.SALE, prices: [ { amount: 1000, variant_id, currency_code: 'eur' } ] }) .then(({ price_list }) => { console.log(price_list.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/price-lists' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "New Price List", "description": "A new price list", "type": "sale", "prices": [ { "amount": 1000, "variant_id": "afafa", "currency_code": "eur" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: price_list: $ref: '#/components/schemas/price_list' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetPriceLists summary: List Price Lists description: Retrieves a list of Price Lists. x-authenticated: true parameters: - in: query name: limit description: The number of items to get schema: type: number default: '10' - in: query name: offset description: The offset at which to get items schema: type: number default: '0' - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each item of the result. schema: type: string - in: query name: order description: field to order results by. schema: type: string - in: query name: id description: ID to search for. schema: type: string - in: query name: q description: >- query to search in price list description, price list name, and customer group name fields. schema: type: string - in: query name: status style: form explode: false description: Status to search for. schema: type: array items: type: string enum: - active - draft - in: query name: name description: price list name to search for. schema: type: string - in: query name: customer_groups style: form explode: false description: Customer Group IDs to search for. schema: type: array items: type: string - in: query name: type style: form explode: false description: Type to search for. schema: type: array items: type: string enum: - sale - override - in: query name: created_at description: Date comparison for when resulting price lists were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting price lists were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: deleted_at description: Date comparison for when resulting price lists were deleted. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.list() .then(({ price_lists, limit, offset, count }) => { console.log(price_lists.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/price-lists' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: price_lists: type: array items: $ref: '#/components/schemas/price_list' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/price-lists/{id}': delete: operationId: DeletePriceListsPriceList summary: Delete a Price List description: Deletes a Price List x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Price List to delete. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.delete(price_list_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Price List. object: type: string description: The type of the object that was deleted. default: price-list deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetPriceListsPriceList summary: Get a Price List description: Retrieves a Price List. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Price List. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.retrieve(price_list_id) .then(({ price_list }) => { console.log(price_list.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: price_list: $ref: '#/components/schemas/price_list' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostPriceListsPriceListPriceList summary: Update a Price List description: Updates a Price List x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Price List. schema: type: string requestBody: content: application/json: schema: properties: name: description: The name of the Price List type: string description: description: A description of the Price List. type: string starts_at: description: >- The date with timezone that the Price List starts being valid. type: string format: date ends_at: description: The date with timezone that the Price List ends being valid. type: string format: date type: description: The type of the Price List. type: string enum: - sale - override status: description: The status of the Price List. type: string enum: - active - draft prices: description: The prices of the Price List. type: array items: required: - amount - variant_id properties: id: description: The ID of the price. type: string region_id: description: >- The ID of the Region for which the price is used. Only required if currecny_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. variant_id: description: The ID of the Variant for which the price is used. type: string amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: The minimum quantity for which the price will be used. type: integer max_quantity: description: The maximum quantity for which the price will be used. type: integer customer_groups: type: array description: A list of customer groups that the Price List applies to. items: required: - id properties: id: description: The ID of a customer group type: string includes_tax: description: '[EXPERIMENTAL] Tax included in prices of price list' type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.update(price_list_id, { name: 'New Price List' }) .then(({ price_list }) => { console.log(price_list.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/price-lists/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "New Price List" }' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: price_list: $ref: '#/components/schemas/price_list' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/price-lists/{id}/products/{product_id}/prices': delete: operationId: DeletePriceListsPriceListProductsProductPrices summary: Delete Product's Prices description: Delete all the prices related to a specific product in a price list x-authenticated: true parameters: - in: path name: id required: true description: >- The ID of the Price List that the Money Amounts that will be deleted belongs to. schema: type: string - in: path name: product_id required: true description: The ID of the product from which the money amount will be deleted. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.deleteProductPrices(price_list_id, product_id) .then(({ ids, object, deleted }) => { console.log(ids.length); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/products/{product_id}/prices' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: ids: type: array description: The price ids that have been deleted. items: type: string object: type: string description: The type of the object that was deleted. default: money-amount deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/price-lists/{id}/variants/{variant_id}/prices': delete: operationId: DeletePriceListsPriceListVariantsVariantPrices summary: Delete Variant's Prices description: Delete all the prices related to a specific variant in a price list x-authenticated: true parameters: - in: path name: id required: true description: >- The ID of the Price List that the Money Amounts that will be deleted belongs to. schema: type: string - in: path name: variant_id required: true description: The ID of the variant from which the money amount will be deleted. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.deleteVariantPrices(price_list_id, variant_id) .then(({ ids, object, deleted }) => { console.log(ids); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/price-lists/{id}/variants/{variant_id}/prices' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Price List responses: '200': description: OK content: application/json: schema: properties: ids: type: array description: The price ids that have been deleted. items: type: string object: type: string description: The type of the object that was deleted. default: money-amount deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/price-lists/{id}/products': get: operationId: GetPriceListsPriceListProducts summary: List Products description: Retrieves a list of Product that are part of a Price List x-authenticated: true parameters: - in: path name: id required: true description: ID of the price list. schema: type: string - in: query name: q description: >- Query used for searching product title and description, variant title and sku, and collection title. schema: type: string - in: query name: id description: ID of the product to search for. schema: type: string - in: query name: status description: Product status to search for style: form explode: false schema: type: array items: type: string enum: - draft - proposed - published - rejected - in: query name: collection_id description: Collection IDs to search for style: form explode: false schema: type: array items: type: string - in: query name: tags description: Tag IDs to search for style: form explode: false schema: type: array items: type: string - in: query name: title description: product title to search for. schema: type: string - in: query name: description description: product description to search for. schema: type: string - in: query name: handle description: product handle to search for. schema: type: string - in: query name: is_giftcard description: Search for giftcards using is_giftcard=true. schema: type: string - in: query name: type description: to search for. schema: type: string - in: query name: order description: field to sort results by. schema: type: string - in: query name: created_at description: Date comparison for when resulting products were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting products were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: deleted_at description: Date comparison for when resulting products were deleted. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: offset description: How many products to skip in the result. schema: type: integer default: 0 - in: query name: limit description: Limit the number of products returned. schema: type: integer default: 50 - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each product of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each product of the result. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.priceLists.listProducts(price_list_id) .then(({ products, limit, offset, count }) => { console.log(products.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/price-lists/{id}/products' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: products: type: array items: $ref: '#/components/schemas/product' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /product-tags: get: operationId: GetProductTags summary: List Product Tags description: Retrieve a list of Product Tags. x-authenticated: true parameters: - in: query name: limit description: The number of tags to return. schema: type: integer default: 10 - in: query name: offset description: The number of items to skip before the results. schema: type: integer default: 0 - in: query name: order description: The field to sort items by. schema: type: string - in: query name: discount_condition_id description: The discount condition id on which to filter the tags. schema: type: string - in: query name: value style: form explode: false description: The tag values to search for schema: type: array items: type: string - in: query name: q description: A query string to search values for schema: type: string - in: query name: id style: form explode: false description: The tag IDs to search for schema: type: array items: type: string - in: query name: created_at description: Date comparison for when resulting product tags were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting product tags were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date x-codeSamples: - lang: JavaScript label: JS Client source: > 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.productTags.list() .then(({ product_tags }) => { console.log(product_tags.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/product-tags' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product Tag responses: '200': description: OK content: application/json: schema: properties: product_tags: $ref: '#/components/schemas/product_tag' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /product-types: get: operationId: GetProductTypes summary: List Product Types description: Retrieve a list of Product Types. x-authenticated: true parameters: - in: query name: limit description: The number of types to return. schema: type: integer default: 10 - in: query name: offset description: The number of items to skip before the results. schema: type: integer default: 0 - in: query name: order description: The field to sort items by. schema: type: string - in: query name: discount_condition_id description: The discount condition id on which to filter the product types. schema: type: string - in: query name: value style: form explode: false description: The type values to search for schema: type: array items: type: string - in: query name: id style: form explode: false description: The type IDs to search for schema: type: array items: type: string - in: query name: q description: A query string to search values for schema: type: string - in: query name: created_at description: Date comparison for when resulting product types were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting product types were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date x-codeSamples: - lang: JavaScript label: JS Client source: > 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.productTypes.list() .then(({ product_types }) => { console.log(product_types.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/product-types' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product Type responses: '200': description: OK content: application/json: schema: properties: product_types: $ref: '#/components/schemas/product_type' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}/options': post: operationId: PostProductsProductOptions summary: Add an Option x-authenticated: true description: Adds a Product Option to a Product parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string requestBody: content: application/json: schema: required: - title properties: title: description: >- The title the Product Option will be identified by i.e. "Size" type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.addOption(product_id, { title: 'Size' }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Size" }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /products: post: operationId: PostProducts summary: Create a Product x-authenticated: true description: Creates a Product requestBody: content: application/json: schema: required: - title properties: title: description: The title of the Product type: string subtitle: description: The subtitle of the Product type: string description: description: A description of the Product. type: string is_giftcard: description: >- A flag to indicate if the Product represents a Gift Card. Purchasing Products with this flag set to `true` will result in a Gift Card being created. type: boolean default: false discountable: description: >- A flag to indicate if discounts can be applied to the LineItems generated from this Product type: boolean default: true images: description: Images of the Product. type: array items: type: string thumbnail: description: The thumbnail to use for the Product. type: string handle: description: A unique handle to identify the Product by. type: string status: description: The status of the product. type: string enum: - draft - proposed - published - rejected default: draft type: description: The Product Type to associate the Product with. type: object required: - value properties: id: description: The ID of the Product Type. type: string value: description: The value of the Product Type. type: string collection_id: description: The ID of the Collection the Product should belong to. type: string tags: description: Tags to associate the Product with. type: array items: required: - value properties: id: description: The ID of an existing Tag. type: string value: description: 'The value of the Tag, these will be upserted.' type: string sales_channels: description: '[EXPERIMENTAL] Sales channels to associate the Product with.' type: array items: required: - id properties: id: description: The ID of an existing Sales channel. type: string options: description: >- The Options that the Product should have. These define on which properties the Product's Product Variants will differ. type: array items: required: - title properties: title: description: The title to identify the Product Option by. type: string variants: description: A list of Product Variants to create with the Product. type: array items: required: - title properties: title: description: The title to identify the Product Variant by. type: string sku: description: The unique SKU for the Product Variant. type: string ean: description: The EAN number of the item. type: string upc: description: The UPC number of the item. type: string barcode: description: A generic GTIN field for the Product Variant. type: string hs_code: description: The Harmonized System code for the Product Variant. type: string inventory_quantity: description: The amount of stock kept for the Product Variant. type: integer default: 0 allow_backorder: description: >- Whether the Product Variant can be purchased when out of stock. type: boolean manage_inventory: description: >- Whether Medusa should keep track of the inventory for this Product Variant. type: boolean weight: description: The wieght of the Product Variant. type: number length: description: The length of the Product Variant. type: number height: description: The height of the Product Variant. type: number width: description: The width of the Product Variant. type: number origin_country: description: The country of origin of the Product Variant. type: string mid_code: description: >- The Manufacturer Identification code for the Product Variant. type: string material: description: The material composition of the Product Variant. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object prices: type: array items: required: - amount properties: region_id: description: >- The ID of the Region for which the price is used. Only required if currency_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_4217#Active_codes description: See a list of codes. amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: >- The minimum quantity for which the price will be used. type: integer max_quantity: description: >- The maximum quantity for which the price will be used. type: integer options: type: array items: required: - value properties: value: description: >- The value to give for the Product Option at the same index in the Product's `options` field. type: string weight: description: The weight of the Product. type: number length: description: The length of the Product. type: number height: description: The height of the Product. type: number width: description: The width of the Product. type: number hs_code: description: The Harmonized System code for the Product Variant. type: string origin_country: description: The country of origin of the Product. type: string mid_code: description: The Manufacturer Identification code for the Product. type: string material: description: The material composition of the Product. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.create({ title: 'Shirt', is_giftcard: false, discountable: true }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Shirt" }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetProducts summary: List Products description: Retrieves a list of Product x-authenticated: true parameters: - in: query name: q description: >- Query used for searching product title and description, variant title and sku, and collection title. schema: type: string - in: query name: discount_condition_id description: The discount condition id on which to filter the product. schema: type: string - in: query name: id style: form explode: false description: Filter by product IDs. schema: oneOf: - type: string description: ID of the product to search for. - type: array items: type: string description: ID of a product. - in: query name: status style: form explode: false description: Status to search for schema: type: array items: type: string enum: - draft - proposed - published - rejected - in: query name: collection_id style: form explode: false description: Collection ids to search for. schema: type: array items: type: string - in: query name: tags style: form explode: false description: Tag IDs to search for schema: type: array items: type: string - in: query name: price_list_id style: form explode: false description: Price List IDs to search for schema: type: array items: type: string - in: query name: sales_channel_id style: form explode: false description: Sales Channel IDs to filter products by schema: type: array items: type: string - in: query name: type_id style: form explode: false description: Type IDs to filter products by schema: type: array items: type: string - in: query name: title description: title to search for. schema: type: string - in: query name: description description: description to search for. schema: type: string - in: query name: handle description: handle to search for. schema: type: string - in: query name: is_giftcard description: Search for giftcards using is_giftcard=true. schema: type: boolean - in: query name: created_at description: Date comparison for when resulting products were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting products were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: deleted_at description: Date comparison for when resulting products were deleted. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: offset description: How many products to skip in the result. schema: type: integer default: 0 - in: query name: limit description: Limit the number of products returned. schema: type: integer default: 50 - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each product of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each product of the result. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.list() .then(({ products, limit, offset, count }) => { console.log(products.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/products' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: products: type: array items: $ref: '#/components/schemas/product' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}/variants': post: operationId: PostProductsProductVariants summary: Create a Product Variant description: >- Creates a Product Variant. Each Product Variant must have a unique combination of Product Option Values. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string requestBody: content: application/json: schema: required: - title - prices - options properties: title: description: The title to identify the Product Variant by. type: string sku: description: The unique SKU for the Product Variant. type: string ean: description: The EAN number of the item. type: string upc: description: The UPC number of the item. type: string barcode: description: A generic GTIN field for the Product Variant. type: string hs_code: description: The Harmonized System code for the Product Variant. type: string inventory_quantity: description: The amount of stock kept for the Product Variant. type: integer default: 0 allow_backorder: description: >- Whether the Product Variant can be purchased when out of stock. type: boolean manage_inventory: description: >- Whether Medusa should keep track of the inventory for this Product Variant. type: boolean weight: description: The wieght of the Product Variant. type: number length: description: The length of the Product Variant. type: number height: description: The height of the Product Variant. type: number width: description: The width of the Product Variant. type: number origin_country: description: The country of origin of the Product Variant. type: string mid_code: description: >- The Manufacturer Identification code for the Product Variant. type: string material: description: The material composition of the Product Variant. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object prices: type: array items: required: - amount properties: id: description: The ID of the price. type: string region_id: description: >- The ID of the Region for which the price is used. Only required if currency_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: The minimum quantity for which the price will be used. type: integer max_quantity: description: The maximum quantity for which the price will be used. type: integer options: type: array items: required: - option_id - value properties: option_id: description: The ID of the Product Option to set the value for. type: string value: description: The value to give for the Product Option. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.createVariant(product_id, { title: 'Color', prices: [ { amount: 1000, currency_code: "eur" } ], options: [ { option_id, value: 'S' } ], inventory_quantity: 100 }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/{id}/variants' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Color", "prices": [ { "amount": 1000, "currency_code": "eur" } ], "options": [ { "option_id": "asdasf", "value": "S" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetProductsProductVariants summary: List a Product's Variants description: Retrieves a list of the Product Variants associated with a Product. x-authenticated: true parameters: - in: path name: id required: true description: ID of the product to search for the variants. schema: type: string - in: query name: fields description: Comma separated string of the column to select. schema: type: string - in: query name: expand description: Comma separated string of the relations to include. schema: type: string - in: query name: offset description: How many items to skip before the results. schema: type: integer default: 0 - in: query name: limit description: Limit the number of items returned. schema: type: integer default: 100 x-codeSamples: - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/products/{id}/variants' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: variants: type: array items: $ref: '#/components/schemas/product_variant' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}/options/{option_id}': delete: operationId: DeleteProductsProductOptionsOption summary: Delete a Product Option description: >- Deletes a Product Option. Before a Product Option can be deleted all Option Values for the Product Option must be the same. You may, for example, have to delete some of your variants prior to deleting the Product Option x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string - in: path name: option_id required: true description: The ID of the Product Option. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.deleteOption(product_id, option_id) .then(({ option_id, object, delete, product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: option_id: type: string description: The ID of the deleted Product Option object: type: string description: The type of the object that was deleted. default: option deleted: type: boolean description: Whether or not the items were deleted. default: true product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostProductsProductOptionsOption summary: Update a Product Option description: Updates a Product Option x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string - in: path name: option_id required: true description: The ID of the Product Option. schema: type: string requestBody: content: application/json: schema: required: - title properties: title: description: The title of the Product Option type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.updateOption(product_id, option_id, { title: 'Size' }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/{id}/options/{option_id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Size" }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}': delete: operationId: DeleteProductsProduct summary: Delete a Product description: Deletes a Product and it's associated Product Variants. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.delete(product_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/products/asfsaf' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Product. object: type: string description: The type of the object that was deleted. default: product deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetProductsProduct summary: Get a Product description: Retrieves a Product. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.retrieve(product_id) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/products/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostProductsProduct summary: Update a Product description: Updates a Product x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string requestBody: content: application/json: schema: properties: title: description: The title of the Product type: string subtitle: description: The subtitle of the Product type: string description: description: A description of the Product. type: string discountable: description: >- A flag to indicate if discounts can be applied to the LineItems generated from this Product type: boolean images: description: Images of the Product. type: array items: type: string thumbnail: description: The thumbnail to use for the Product. type: string handle: description: A unique handle to identify the Product by. type: string status: description: The status of the product. type: string enum: - draft - proposed - published - rejected type: description: The Product Type to associate the Product with. type: object required: - value properties: id: description: The ID of the Product Type. type: string value: description: The value of the Product Type. type: string collection_id: description: The ID of the Collection the Product should belong to. type: string tags: description: Tags to associate the Product with. type: array items: required: - value properties: id: description: The ID of an existing Tag. type: string value: description: 'The value of the Tag, these will be upserted.' type: string sales_channels: description: '[EXPERIMENTAL] Sales channels to associate the Product with.' type: array items: required: - id properties: id: description: The ID of an existing Sales channel. type: string variants: description: A list of Product Variants to create with the Product. type: array items: properties: id: description: The ID of the Product Variant. type: string title: description: The title to identify the Product Variant by. type: string sku: description: The unique SKU for the Product Variant. type: string ean: description: The EAN number of the item. type: string upc: description: The UPC number of the item. type: string barcode: description: A generic GTIN field for the Product Variant. type: string hs_code: description: The Harmonized System code for the Product Variant. type: string inventory_quantity: description: The amount of stock kept for the Product Variant. type: integer allow_backorder: description: >- Whether the Product Variant can be purchased when out of stock. type: boolean manage_inventory: description: >- Whether Medusa should keep track of the inventory for this Product Variant. type: boolean weight: description: The wieght of the Product Variant. type: number length: description: The length of the Product Variant. type: number height: description: The height of the Product Variant. type: number width: description: The width of the Product Variant. type: number origin_country: description: The country of origin of the Product Variant. type: string mid_code: description: >- The Manufacturer Identification code for the Product Variant. type: string material: description: The material composition of the Product Variant. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object prices: type: array items: required: - amount properties: id: description: The ID of the Price. type: string region_id: description: >- The ID of the Region for which the price is used. Only required if currency_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_4217#Active_codes description: See a list of codes. amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: >- The minimum quantity for which the price will be used. type: integer max_quantity: description: >- The maximum quantity for which the price will be used. type: integer options: type: array items: required: - option_id - value properties: option_id: description: The ID of the Option. type: string value: description: >- The value to give for the Product Option at the same index in the Product's `options` field. type: string weight: description: The wieght of the Product. type: number length: description: The length of the Product. type: number height: description: The height of the Product. type: number width: description: The width of the Product. type: number origin_country: description: The country of origin of the Product. type: string mid_code: description: The Manufacturer Identification code for the Product. type: string material: description: The material composition of the Product. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.update(product_id, { title: 'Shirt', images: [] }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Size" }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}/variants/{variant_id}': delete: operationId: DeleteProductsProductVariantsVariant summary: Delete a Product Variant description: Deletes a Product Variant. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string - in: path name: variant_id required: true description: The ID of the Product Variant. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.deleteVariant(product_id, variant_id) .then(({ variant_id, object, deleted, product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/products/{id}/variants/{variant_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: variant_id: type: string description: The ID of the deleted Product Variant. object: type: string description: The type of the object that was deleted. default: variant deleted: type: boolean description: Whether or not the items were deleted. default: true product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostProductsProductVariantsVariant summary: Update a Product Variant description: Update a Product Variant. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string - in: path name: variant_id required: true description: The ID of the Product Variant. schema: type: string requestBody: content: application/json: schema: required: - prices properties: title: description: The title to identify the Product Variant by. type: string sku: description: The unique SKU for the Product Variant. type: string ean: description: The EAN number of the item. type: string upc: description: The UPC number of the item. type: string barcode: description: A generic GTIN field for the Product Variant. type: string hs_code: description: The Harmonized System code for the Product Variant. type: string inventory_quantity: description: The amount of stock kept for the Product Variant. type: integer allow_backorder: description: >- Whether the Product Variant can be purchased when out of stock. type: boolean manage_inventory: description: >- Whether Medusa should keep track of the inventory for this Product Variant. type: boolean weight: description: The weight of the Product Variant. type: number length: description: The length of the Product Variant. type: number height: description: The height of the Product Variant. type: number width: description: The width of the Product Variant. type: number origin_country: description: The country of origin of the Product Variant. type: string mid_code: description: >- The Manufacturer Identification code for the Product Variant. type: string material: description: The material composition of the Product Variant. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object prices: type: array items: required: - amount properties: id: description: The ID of the price. type: string region_id: description: >- The ID of the Region for which the price is used. Only required if currency_code is not provided. type: string currency_code: description: >- The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. amount: description: The amount to charge for the Product Variant. type: integer min_quantity: description: The minimum quantity for which the price will be used. type: integer max_quantity: description: The maximum quantity for which the price will be used. type: integer options: type: array items: required: - option_id - value properties: option_id: description: The ID of the Product Option to set the value for. type: string value: description: The value to give for the Product Option. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.updateVariant(product_id, variant_id, { title: 'Color', prices: [ { amount: 1000, currency_code: "eur" } ], options: [ { option_id, value: 'S' } ], inventory_quantity: 100 }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/asfsaf/variants/saaga' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Color", "prices": [ { "amount": 1000, "currency_code": "eur" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /products/tag-usage: get: operationId: GetProductsTagUsage summary: List Tags Usage Number description: Retrieves a list of Product Tags with how many times each is used. x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.listTags() .then(({ tags }) => { console.log(tags.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/products/tag-usage' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product Tag responses: '200': description: OK content: application/json: schema: properties: tags: type: array items: properties: id: description: The ID of the tag. type: string usage_count: description: The number of products that use this tag. type: string value: description: The value of the tag. type: string '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /products/types: get: operationId: GetProductsTypes summary: List Product Types description: Retrieves a list of Product Types. x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.listTypes() .then(({ types }) => { console.log(types.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/products/types' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: types: type: array items: $ref: '#/components/schemas/product_type' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/products/{id}/metadata': post: operationId: PostProductsProductMetadata summary: Set Product Metadata description: Set metadata key/value pair for Product x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Product. schema: type: string requestBody: content: application/json: schema: required: - key - value properties: key: description: The metadata key type: string value: description: The metadata value type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.products.setMetadata(product_id, { key: 'test', value: 'true' }) .then(({ product }) => { console.log(product.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/products/{id}/metadata' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "key": "test", "value": "true" }' security: - api_token: [] - cookie_auth: [] tags: - Product responses: '200': description: OK content: application/json: schema: properties: product: $ref: '#/components/schemas/product' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/countries': post: operationId: PostRegionsRegionCountries summary: Add Country description: Adds a Country to the list of Countries in a Region x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string requestBody: content: application/json: schema: required: - country_code properties: country_code: description: The 2 character ISO code for the Country. type: string externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements description: See a list of codes. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.addCountry(region_id, { country_code: 'dk' }) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/regions/{region_id}/countries' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "country_code": "dk" }' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/fulfillment-providers': post: operationId: PostRegionsRegionFulfillmentProviders summary: Add Fulfillment Provider description: Adds a Fulfillment Provider to a Region x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string requestBody: content: application/json: schema: required: - provider_id properties: provider_id: description: The ID of the Fulfillment Provider to add. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.addFulfillmentProvider(region_id, { provider_id: 'manual' }) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "provider_id": "manual" }' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/payment-providers': post: operationId: PostRegionsRegionPaymentProviders summary: Add Payment Provider description: Adds a Payment Provider to a Region x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string requestBody: content: application/json: schema: required: - provider_id properties: provider_id: description: The ID of the Payment Provider to add. type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.addPaymentProvider(region_id, { provider_id: 'manual' }) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/regions/{id}/payment-providers' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "provider_id": "manual" }' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /regions: post: operationId: PostRegions summary: Create a Region description: Creates a Region x-authenticated: true requestBody: content: application/json: schema: required: - name - currency_code - tax_rate - payment_providers - fulfillment_providers - countries properties: name: description: The name of the Region type: string currency_code: description: The 3 character ISO currency code to use for the Region. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. tax_code: description: An optional tax code the Region. type: string tax_rate: description: The tax rate to use on Orders in the Region. type: number payment_providers: description: >- A list of Payment Provider IDs that should be enabled for the Region type: array items: type: string fulfillment_providers: description: >- A list of Fulfillment Provider IDs that should be enabled for the Region type: array items: type: string countries: description: >- A list of countries' 2 ISO Characters that should be included in the Region. example: - US type: array items: type: string includes_tax: description: '[EXPERIMENTAL] Tax included in prices of region' type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.create({ name: 'Europe', currency_code: 'eur', tax_rate: 0, payment_providers: [ 'manual' ], fulfillment_providers: [ 'manual' ], countries: [ 'DK' ] }) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/regions' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Europe", "currency_code": "eur", "tax_rate": 0, "payment_providers": [ "manual" ], "fulfillment_providers": [ "manual" ], "countries": [ "DK" ] }' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetRegions summary: List Regions description: Retrieves a list of Regions. x-authenticated: true parameters: - in: query name: limit schema: type: integer default: 50 required: false description: limit the number of regions in response - in: query name: offset schema: type: integer default: 0 required: false description: Offset of regions in response (used for pagination) - in: query name: created_at schema: type: object required: false description: >- Date comparison for when resulting region was created, i.e. less than, greater than etc. - in: query name: updated_at schema: type: object required: false description: >- Date comparison for when resulting region was updated, i.e. less than, greater than etc. - in: query name: deleted_at schema: type: object required: false description: >- Date comparison for when resulting region was deleted, i.e. less than, greater than etc. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.list() .then(({ regions, limit, offset, count }) => { console.log(regions.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/regions' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: regions: type: array items: $ref: '#/components/schemas/region' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}': delete: operationId: DeleteRegionsRegion summary: Delete a Region description: Deletes a Region. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.delete(region_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Region. object: type: string description: The type of the object that was deleted. default: region deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetRegionsRegion summary: Get a Region description: Retrieves a Region. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.retrieve(region_id) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/regions/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostRegionsRegion summary: Update a Region description: Updates a Region x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string requestBody: content: application/json: schema: properties: name: description: The name of the Region type: string currency_code: description: The 3 character ISO currency code to use for the Region. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. automatic_taxes: description: >- If true Medusa will automatically calculate taxes for carts in this region. If false you have to manually call POST /carts/:id/taxes. type: boolean gift_cards_taxable: description: >- Whether gift cards in this region should be applied sales tax when purchasing a gift card type: boolean tax_provider_id: description: >- The ID of the tax provider to use; if null the system tax provider is used type: string tax_code: description: An optional tax code the Region. type: string tax_rate: description: The tax rate to use on Orders in the Region. type: number includes_tax: description: '[EXPERIMENTAL] Tax included in prices of region' type: boolean payment_providers: description: >- A list of Payment Provider IDs that should be enabled for the Region type: array items: type: string fulfillment_providers: description: >- A list of Fulfillment Provider IDs that should be enabled for the Region type: array items: type: string countries: description: >- A list of countries' 2 ISO Characters that should be included in the Region. type: array items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.update(region_id, { name: 'Europe' }) .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/regions/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Europe" }' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/fulfillment-options': get: operationId: GetRegionsRegionFulfillmentOptions summary: List Fulfillment Options description: Gathers all the fulfillment options available to in the Region. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.retrieveFulfillmentOptions(region_id) .then(({ fulfillment_options }) => { console.log(fulfillment_options.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/regions/{id}/fulfillment-options' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: fulfillment_options: type: array items: properties: provider_id: type: string description: ID of the fulfillment provider options: type: array description: fulfillment provider options example: - id: manual-fulfillment - id: manual-fulfillment-return is_return: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/countries/{country_code}': delete: operationId: PostRegionsRegionCountriesCountry summary: Delete Country x-authenticated: true description: Removes a Country from the list of Countries in a Region parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string - in: path name: country_code description: The 2 character ISO code for the Country. required: true schema: type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.deleteCountry(region_id, 'dk') .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/countries/dk' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/fulfillment-providers/{provider_id}': delete: operationId: PostRegionsRegionFulfillmentProvidersProvider summary: Del. Fulfillment Provider description: Removes a Fulfillment Provider. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string - in: path name: provider_id required: true description: The ID of the Fulfillment Provider. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.deleteFulfillmentProvider(region_id, 'manual') .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/fulfillment-providers/manual' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/regions/{id}/payment-providers/{provider_id}': delete: operationId: PostRegionsRegionPaymentProvidersProvider summary: Delete Payment Provider description: Removes a Payment Provider. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Region. schema: type: string - in: path name: provider_id required: true description: The ID of the Payment Provider. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.regions.deletePaymentProvider(region_id, 'manual') .then(({ region }) => { console.log(region.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/regions/{id}/payment-providers/manual' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Region responses: '200': description: OK content: application/json: schema: properties: region: $ref: '#/components/schemas/region' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /return-reasons: post: operationId: PostReturnReasons summary: Create a Return Reason description: Creates a Return Reason x-authenticated: true requestBody: content: application/json: schema: required: - label - value properties: label: description: The label to display to the Customer. type: string value: description: >- The value that the Return Reason will be identified by. Must be unique. type: string parent_return_reason_id: description: The ID of the parent return reason. type: string description: description: An optional description to for the Reason. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returnReasons.create({ label: 'Damaged', value: 'damaged' }) .then(({ return_reason }) => { console.log(return_reason.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/return-reasons' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "label": "Damaged", "value": "damaged" }' security: - api_token: [] - cookie_auth: [] tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetReturnReasons summary: List Return Reasons description: Retrieves a list of Return Reasons. x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returnReasons.list() .then(({ return_reasons }) => { console.log(return_reasons.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/return-reasons' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reasons: type: array items: $ref: '#/components/schemas/return_reason' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/return-reasons/{id}': delete: operationId: DeleteReturnReason summary: Delete a Return Reason description: Deletes a return reason. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the return reason schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returnReasons.delete(return_reason_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/return-reasons/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted return reason object: type: string description: The type of the object that was deleted. default: return_reason deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetReturnReasonsReason summary: Get a Return Reason description: Retrieves a Return Reason. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Return Reason. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returnReasons.retrieve(return_reason_id) .then(({ return_reason }) => { console.log(return_reason.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/return-reasons/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostReturnReasonsReason summary: Update a Return Reason description: Updates a Return Reason x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Return Reason. schema: type: string requestBody: content: application/json: schema: properties: label: description: The label to display to the Customer. type: string value: description: >- The value that the Return Reason will be identified by. Must be unique. type: string description: description: An optional description to for the Reason. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returnReasons.update(return_reason_id, { label: 'Damaged' }) .then(({ return_reason }) => { console.log(return_reason.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/return-reasons/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "label": "Damaged" }' security: - api_token: [] - cookie_auth: [] tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/returns/{id}/cancel': post: operationId: PostReturnsReturnCancel summary: Cancel a Return description: Registers a Return as canceled. parameters: - in: path name: id required: true description: The ID of the Return. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returns.cancel(return_id) .then(({ order }) => { console.log(order.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/cancel' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Return responses: '200': description: OK content: application/json: schema: properties: order: $ref: '#/components/schemas/order' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /returns: get: operationId: GetReturns summary: List Returns description: Retrieves a list of Returns parameters: - in: query name: limit description: The upper limit for the amount of responses returned. schema: type: number default: '50' - in: query name: offset description: The offset of the list returned. schema: type: number default: '0' x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returns.list() .then(({ returns, limit, offset, count }) => { console.log(returns.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/returns' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Return responses: '200': description: OK content: application/json: schema: properties: returns: type: array items: $ref: '#/components/schemas/return' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/returns/{id}/receive': post: operationId: PostReturnsReturnReceive summary: Receive a Return description: >- Registers a Return as received. Updates statuses on Orders and Swaps accordingly. parameters: - in: path name: id required: true description: The ID of the Return. schema: type: string requestBody: content: application/json: schema: required: - items properties: items: description: The Line Items that have been received. type: array items: required: - item_id - quantity properties: item_id: description: The ID of the Line Item. type: string quantity: description: The quantity of the Line Item. type: integer refund: description: The amount to refund. type: number x-codeSamples: - lang: JavaScript label: JS Client source: > 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.returns.receive(return_id, { items: [ { item_id, quantity: 1 } ] }) .then((data) => { console.log(data.return.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/returns/{id}/receive' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "items": [ { "item_id": "asafg", "quantity": 1 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Return responses: '200': description: OK content: application/json: schema: properties: return: $ref: '#/components/schemas/return' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/sales-channels/{id}/products/batch': post: operationId: PostSalesChannelsChannelProductsBatch summary: Add Products description: Assign a batch of product to a sales channel. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Sales channel. schema: type: string requestBody: content: application/json: schema: required: - product_ids properties: product_ids: description: The IDs of the products to add to the Sales Channel type: array items: type: object required: - id properties: id: type: string description: The ID of the product x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.addProducts(sales_channel_id, { product_ids: [ { id: product_id } ] }) .then(({ sales_channel }) => { console.log(sales_channel.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/sales-channels/afasf/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_ids": [ { "id": "{product_id}" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channel: $ref: '#/components/schemas/sales_channel' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteSalesChannelsChannelProductsBatch summary: Delete Products description: Remove a list of products from a sales channel. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Sales Channel schema: type: string requestBody: content: application/json: schema: required: - product_ids properties: product_ids: description: The IDs of the products to delete from the Sales Channel. type: array items: type: object required: - id properties: id: description: The ID of a product type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.removeProducts(sales_channel_id, { product_ids: [ { id: product_id } ] }) .then(({ sales_channel }) => { console.log(sales_channel.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_ids": [ { "id": "{product_id}" } ] }' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channel: $ref: '#/components/schemas/sales_channel' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /sales-channels: post: operationId: PostSalesChannels summary: Create a Sales Channel description: Creates a Sales Channel. x-authenticated: true requestBody: content: application/json: schema: required: - name properties: name: description: The name of the Sales Channel type: string description: description: The description of the Sales Channel type: string is_disabled: description: Whether the Sales Channel is disabled or not. type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.create({ name: 'App', description: 'Mobile app' }) .then(({ sales_channel }) => { console.log(sales_channel.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/sales-channels' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "App" }' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channel: $ref: '#/components/schemas/sales_channel' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetSalesChannels summary: List Sales Channels description: Retrieves a list of sales channels x-authenticated: true parameters: - in: query name: id description: ID of the sales channel schema: type: string - in: query name: name description: Name of the sales channel schema: type: string - in: query name: description description: Description of the sales channel schema: type: string - in: query name: q description: Query used for searching sales channels' names and descriptions. schema: type: string - in: query name: order description: The field to order the results by. schema: type: string - in: query name: created_at description: Date comparison for when resulting collections were created. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: updated_at description: Date comparison for when resulting collections were updated. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: deleted_at description: Date comparison for when resulting collections were deleted. schema: type: object properties: lt: type: string description: filter by dates less than this date format: date gt: type: string description: filter by dates greater than this date format: date lte: type: string description: filter by dates less than or equal to this date format: date gte: type: string description: filter by dates greater than or equal to this date format: date - in: query name: offset description: How many sales channels to skip in the result. schema: type: integer default: 0 - in: query name: limit description: Limit the number of sales channels returned. schema: type: integer default: 20 - in: query name: expand description: >- (Comma separated) Which fields should be expanded in each sales channel of the result. schema: type: string - in: query name: fields description: >- (Comma separated) Which fields should be included in each sales channel of the result. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.list() .then(({ sales_channels, limit, offset, count }) => { console.log(sales_channels.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/sales-channels' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channels: type: array items: $ref: '#/components/schemas/sales_channel' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/sales-channels/{id}': delete: operationId: DeleteSalesChannelsSalesChannel summary: Delete a Sales Channel description: Deletes the sales channel. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Sales channel. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.delete(sales_channel_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/sales-channels/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted sales channel object: type: string description: The type of the object that was deleted. default: sales-channel deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetSalesChannelsSalesChannel summary: Get a Sales Channel description: Retrieves the sales channel. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Sales channel. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.retrieve(sales_channel_id) .then(({ sales_channel }) => { console.log(sales_channel.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/sales-channels/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channel: $ref: '#/components/schemas/sales_channel' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostSalesChannelsSalesChannel summary: Update a Sales Channel description: Updates a Sales Channel. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Sales Channel. schema: type: string requestBody: content: application/json: schema: properties: name: type: string description: Name of the sales channel. description: type: string description: Sales Channel description. is_disabled: type: boolean description: Indication of if the sales channel is active. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.salesChannels.update(sales_channel_id, { name: 'App' }) .then(({ sales_channel }) => { console.log(sales_channel.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/sales-channels/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "App" }' security: - api_token: [] - cookie_auth: [] tags: - Sales Channel responses: '200': description: OK content: application/json: schema: properties: sales_channel: $ref: '#/components/schemas/sales_channel' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /shipping-options: post: operationId: PostShippingOptions summary: Create Shipping Option description: Creates a Shipping Option x-authenticated: true requestBody: content: application/json: schema: required: - name - region_id - provider_id - data - price_type properties: name: description: The name of the Shipping Option type: string region_id: description: >- The ID of the Region in which the Shipping Option will be available. type: string provider_id: description: >- The ID of the Fulfillment Provider that handles the Shipping Option. type: string profile_id: description: >- The ID of the Shipping Profile to add the Shipping Option to. type: number data: description: >- The data needed for the Fulfillment Provider to handle shipping with this Shipping Option. type: object price_type: description: The type of the Shipping Option price. type: string enum: - flat_rate - calculated amount: description: The amount to charge for the Shipping Option. type: integer requirements: description: >- The requirements that must be satisfied for the Shipping Option to be available. type: array items: required: - type - amount properties: type: description: The type of the requirement type: string enum: - max_subtotal - min_subtotal amount: description: The amount to compare with. type: integer is_return: description: Whether the Shipping Option defines a return shipment. type: boolean default: false admin_only: description: 'If true, the option can be used for draft orders' type: boolean default: false metadata: description: >- An optional set of key-value pairs with additional information. type: object includes_tax: description: '[EXPERIMENTAL] Tax included in prices of shipping option' type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingOptions.create({ name: 'PostFake', region_id: "saasf", provider_id: "manual", data: { }, price_type: 'flat_rate' }) .then(({ shipping_option }) => { console.log(shipping_option.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/shipping-options' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "PostFake", "region_id": "afasf", "provider_id": "manual", "data": {}, "price_type": "flat_rate" }' security: - api_token: [] - cookie_auth: [] tags: - Shipping Option responses: '200': description: OK content: application/json: schema: properties: shipping_option: $ref: '#/components/schemas/shipping_option' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetShippingOptions summary: List Shipping Options description: Retrieves a list of Shipping Options. x-authenticated: true parameters: - in: query name: region_id schema: type: string description: Region ID to fetch options from - in: query name: is_return schema: type: boolean description: Flag for fetching return options only - in: query name: admin_only schema: type: boolean description: Flag for fetching admin specific options x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingOptions.list() .then(({ shipping_options, count }) => { console.log(shipping_options.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/shipping-options' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Option responses: '200': description: OK content: application/json: schema: properties: shipping_options: type: array items: $ref: '#/components/schemas/shipping_option' count: type: integer description: The total number of items available '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/shipping-options/{id}': delete: operationId: DeleteShippingOptionsOption summary: Delete a Shipping Option description: Deletes a Shipping Option. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Option. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingOptions.delete(option_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/shipping-options/{option_id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Option responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Shipping Option. object: type: string description: The type of the object that was deleted. default: shipping-option deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetShippingOptionsOption summary: Get a Shipping Option description: Retrieves a Shipping Option. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Option. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingOptions.retrieve(option_id) .then(({ shipping_option }) => { console.log(shipping_option.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/shipping-options/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Option responses: '200': description: OK content: application/json: schema: properties: shipping_option: $ref: '#/components/schemas/shipping_option' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostShippingOptionsOption summary: Update Shipping Option description: Updates a Shipping Option x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Option. schema: type: string requestBody: content: application/json: schema: required: - requirements properties: name: description: The name of the Shipping Option type: string amount: description: The amount to charge for the Shipping Option. type: integer admin_only: description: 'If true, the option can be used for draft orders' type: boolean metadata: description: >- An optional set of key-value pairs with additional information. type: object requirements: description: >- The requirements that must be satisfied for the Shipping Option to be available. type: array items: required: - type - amount properties: id: description: The ID of the requirement type: string type: description: The type of the requirement type: string enum: - max_subtotal - min_subtotal amount: description: The amount to compare with. type: integer includes_tax: description: '[EXPERIMENTAL] Tax included in prices of shipping option' type: boolean x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingOptions.update(option_id, { name: 'PostFake', requirements: [ { id, type: 'max_subtotal', amount: 1000 } ] }) .then(({ shipping_option }) => { console.log(shipping_option.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/shipping-options/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "requirements": [ { "type": "max_subtotal", "amount": 1000 } ] }' security: - api_token: [] - cookie_auth: [] tags: - Shipping Option responses: '200': description: OK content: application/json: schema: properties: shipping_option: $ref: '#/components/schemas/shipping_option' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /shipping-profiles: post: operationId: PostShippingProfiles summary: Create a Shipping Profile description: Creates a Shipping Profile x-authenticated: true requestBody: content: application/json: schema: required: - name properties: name: description: The name of the Shipping Profile type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingProfiles.create({ name: 'Large Products' }) .then(({ shipping_profile }) => { console.log(shipping_profile.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Large Products" }' security: - api_token: [] - cookie_auth: [] tags: - Shipping Profile responses: '200': description: OK content: application/json: schema: properties: shipping_profile: $ref: '#/components/schemas/shipping_profile' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetShippingProfiles summary: List Shipping Profiles description: Retrieves a list of Shipping Profile. x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingProfiles.list() .then(({ shipping_profiles }) => { console.log(shipping_profiles.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Profile responses: '200': description: OK content: application/json: schema: properties: shipping_profiles: type: array items: $ref: '#/components/schemas/shipping_profile' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/shipping-profiles/{id}': delete: operationId: DeleteShippingProfilesProfile summary: Delete a Shipping Profile description: Deletes a Shipping Profile. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Profile. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingProfiles.delete(profile_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/shipping-profiles/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Profile responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Shipping Profile. object: type: string description: The type of the object that was deleted. default: shipping_profile deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetShippingProfilesProfile summary: Get a Shipping Profile description: Retrieves a Shipping Profile. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Profile. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingProfiles.retrieve(profile_id) .then(({ shipping_profile }) => { console.log(shipping_profile.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/shipping-profiles/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Shipping Profile responses: '200': description: OK content: application/json: schema: properties: shipping_profile: $ref: '#/components/schemas/shipping_profile' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostShippingProfilesProfile summary: Update a Shipping Profile description: Updates a Shipping Profile parameters: - in: path name: id required: true description: The ID of the Shipping Profile. schema: type: string requestBody: content: application/json: schema: properties: name: description: The name of the Shipping Profile type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.shippingProfiles.update(shipping_profile_id, { name: 'Large Products' }) .then(({ shipping_profile }) => { console.log(shipping_profile.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/shipping-profiles/{id} \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Large Products" }' security: - api_token: [] - cookie_auth: [] tags: - Shipping Profile responses: '200': description: OK content: application/json: schema: properties: shipping_profile: $ref: '#/components/schemas/shipping_profile' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/store/currencies/{code}': post: operationId: PostStoreCurrenciesCode summary: Add a Currency Code description: Adds a Currency Code to the available currencies. x-authenticated: true parameters: - in: path name: code required: true description: The 3 character ISO currency code. schema: type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.addCurrency('eur') .then(({ store }) => { console.log(store.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/store/currencies/eur' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: store: $ref: '#/components/schemas/store' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteStoreCurrenciesCode summary: Delete a Currency Code description: Removes a Currency Code from the available currencies. x-authenticated: true parameters: - in: path name: code required: true description: The 3 character ISO currency code. schema: type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.deleteCurrency('eur') .then(({ store }) => { console.log(store.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/store/currencies/eur' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: store: $ref: '#/components/schemas/store' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /store: get: operationId: GetStore summary: Get Store details description: Retrieves the Store details x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.retrieve() .then(({ store }) => { console.log(store.id); }); - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/store' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: store: $ref: '#/components/schemas/store' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostStore summary: Update Store Details description: Updates the Store details x-authenticated: true requestBody: content: application/json: schema: properties: name: description: The name of the Store type: string swap_link_template: description: >- A template for Swap links - use `{{cart_id}}` to insert the Swap Cart id type: string payment_link_template: description: >- A template for payment links links - use `{{cart_id}}` to insert the Cart id type: string invite_link_template: description: >- A template for invite links - use `{{invite_token}}` to insert the invite token type: string default_currency_code: description: The default currency code for the Store. type: string externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currencies: description: Array of currencies in 2 character ISO code format. type: array items: type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.update({ name: 'Medusa Store' }) .then(({ store }) => { console.log(store.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/store' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Medusa Store" }' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: store: $ref: '#/components/schemas/store' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /store/payment-providers: get: operationId: GetStorePaymentProviders summary: List Payment Providers description: Retrieves the configured Payment Providers x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.listPaymentProviders() .then(({ payment_providers }) => { console.log(payment_providers.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/store/payment-providers' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: payment_providers: type: array items: $ref: '#/components/schemas/payment_provider' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /store/tax-providers: get: operationId: GetStoreTaxProviders summary: List Tax Providers description: Retrieves the configured Tax Providers x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.store.listTaxProviders() .then(({ tax_providers }) => { console.log(tax_providers.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/store/tax-providers' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Store responses: '200': description: OK content: application/json: schema: properties: tax_providers: type: array items: $ref: '#/components/schemas/tax_provider' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/swaps/{id}': get: operationId: GetSwapsSwap summary: Get a Swap description: Retrieves a Swap. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Swap. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.swaps.retrieve(swap_id) .then(({ swap }) => { console.log(swap.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/swaps/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: swap: $ref: '#/components/schemas/swap' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /swaps: get: operationId: GetSwaps summary: List Swaps description: Retrieves a list of Swaps. parameters: - in: query name: limit description: The upper limit for the amount of responses returned. schema: type: number default: '50' - in: query name: offset description: The offset of the list returned. schema: type: number default: '0' x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.swaps.list() .then(({ swaps }) => { console.log(swaps.length); }); - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/swaps' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Swap responses: '200': description: OK content: application/json: schema: properties: swaps: type: array items: $ref: '#/components/schemas/swap' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/tax-rates/{id}/product-types/batch': post: operationId: PostTaxRatesTaxRateProductTypes summary: Add to Product Types description: Associates a Tax Rate with a list of Product Types parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - product_types properties: product_types: type: array description: >- The IDs of the types of products to associate with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.addProductTypes(tax_rate_id, { product_types: [ product_type_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_types": [ "{product_type_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteTaxRatesTaxRateProductTypes summary: Delete from Product Types description: Removes a Tax Rate from a list of Product Types parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - product_types properties: product_types: type: array description: >- The IDs of the types of products to remove association with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.removeProductTypes(tax_rate_id, { product_types: [ product_type_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/product-types/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "product_types": [ "{product_type_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/tax-rates/{id}/products/batch': post: operationId: PostTaxRatesTaxRateProducts summary: Add to Products description: Associates a Tax Rate with a list of Products parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - products properties: products: type: array description: The IDs of the products to associate with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.addProducts(tax_rate_id, { products: [ product_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "products": [ "{product_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteTaxRatesTaxRateProducts summary: Delete from Products description: Removes a Tax Rate from a list of Products parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - products properties: products: type: array description: >- The IDs of the products to remove association with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.removeProducts(tax_rate_id, { products: [ product_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/products/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "products": [ "{product_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/tax-rates/{id}/shipping-options/batch': post: operationId: PostTaxRatesTaxRateShippingOptions summary: Add to Shipping Options description: Associates a Tax Rate with a list of Shipping Options parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - shipping_options properties: shipping_options: type: array description: >- The IDs of the shipping options to associate with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.addShippingOptions(tax_rate_id, { shipping_options: [ shipping_option_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "shipping_options": [ "{shipping_option_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' delete: operationId: DeleteTaxRatesTaxRateShippingOptions summary: Del. for Shipping Options description: Removes a Tax Rate from a list of Shipping Options parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - shipping_options properties: shipping_options: type: array description: >- The IDs of the shipping options to remove association with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.removeShippingOptions(tax_rate_id, { shipping_options: [ shipping_option_id ] }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}/shipping-options/batch' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "shipping_options": [ "{shipping_option_id}" ] }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /tax-rates: post: operationId: PostTaxRates summary: Create a Tax Rate description: Creates a Tax Rate parameters: - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: required: - code - name - region_id properties: code: type: string description: A code to identify the tax type by name: type: string description: A human friendly name for the tax region_id: type: string description: The ID of the Region that the rate belongs to rate: type: number description: The numeric rate to charge products: type: array description: The IDs of the products associated with this tax rate items: type: string shipping_options: type: array description: >- The IDs of the shipping options associated with this tax rate items: type: string product_types: type: array description: >- The IDs of the types of products associated with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.create({ code: 'TEST', name: 'New Tax Rate', region_id }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/tax-rates' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "code": "TEST", "name": "New Tax Rate", "region_id": "{region_id}" }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetTaxRates summary: List Tax Rates description: Retrieves a list of TaxRates x-authenticated: true parameters: - in: query name: name description: Name of tax rate to retrieve schema: type: string - in: query name: region_id style: form explode: false description: Filter by Region ID schema: oneOf: - type: string - type: array items: type: string - in: query name: code description: code to search for. schema: type: string - in: query name: rate style: form explode: false description: Filter by Rate schema: oneOf: - type: number - type: object properties: lt: type: number description: filter by rates less than this number gt: type: number description: filter by rates greater than this number lte: type: number description: filter by rates less than or equal to this number gte: type: number description: filter by rates greater than or equal to this number - in: query name: offset description: How many tax rates to skip before retrieving the result. schema: type: integer default: 0 - in: query name: limit description: Limit the number of tax rates returned. schema: type: integer default: 50 - in: query name: fields description: Which fields should be included in each item. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved for each item. style: form explode: false schema: type: array items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.list() .then(({ tax_rates, limit, offset, count }) => { console.log(tax_rates.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/tax-rates' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rates: type: array items: $ref: '#/components/schemas/tax_rate' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/tax-rates/{id}': delete: operationId: DeleteTaxRatesTaxRate summary: Delete a Tax Rate description: Deletes a Tax Rate x-authenticated: true parameters: - in: path name: id required: true description: The ID of the Shipping Option. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.delete(tax_rate_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/tax-rates/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted Shipping Option. object: type: string description: The type of the object that was deleted. default: tax-rate deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetTaxRatesTaxRate summary: Get a Tax Rate description: Retrieves a TaxRate parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.retrieve(tax_rate_id) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/tax-rates/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostTaxRatesTaxRate summary: Update a Tax Rate description: Updates a Tax Rate parameters: - in: path name: id required: true description: ID of the tax rate. schema: type: string - in: query name: fields description: Which fields should be included in the result. style: form explode: false schema: type: array items: type: string - in: query name: expand description: Which fields should be expanded and retrieved in the result. style: form explode: false schema: type: array items: type: string x-authenticated: true requestBody: content: application/json: schema: properties: code: type: string description: A code to identify the tax type by name: type: string description: A human friendly name for the tax region_id: type: string description: The ID of the Region that the rate belongs to rate: type: number description: The numeric rate to charge products: type: array description: The IDs of the products associated with this tax rate items: type: string shipping_options: type: array description: >- The IDs of the shipping options associated with this tax rate items: type: string product_types: type: array description: >- The IDs of the types of products associated with this tax rate items: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.taxRates.update(tax_rate_id, { name: 'New Tax Rate' }) .then(({ tax_rate }) => { console.log(tax_rate.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/tax-rates/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "New Tax Rate" }' security: - api_token: [] - cookie_auth: [] tags: - Tax Rate responses: '200': description: OK content: application/json: schema: properties: tax_rate: $ref: '#/components/schemas/tax_rate' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /uploads/protected: post: operationId: PostUploadsProtected summary: Upload files with acl or in a non-public bucket description: >- Uploads at least one file to the specific fileservice that is installed in Medusa. x-authenticated: true requestBody: content: multipart/form-data: schema: type: object properties: files: type: string format: binary x-codeSamples: - lang: JavaScript label: JS Client source: > 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.uploads.createProtected(file) .then(({ uploads }) => { console.log(uploads.length); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/uploads/protected' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: image/jpeg' \ --form 'files=@""' \ --form 'files=@""' security: - api_token: [] - cookie_auth: [] tags: - Upload responses: '200': description: OK content: application/json: schema: properties: uploads: type: array items: type: object properties: url: type: string description: The URL of the uploaded file. format: uri '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /uploads: post: operationId: PostUploads summary: Upload files description: >- Uploads at least one file to the specific fileservice that is installed in Medusa. x-authenticated: true requestBody: content: multipart/form-data: schema: type: object properties: files: type: string format: binary x-codeSamples: - lang: JavaScript label: JS Client source: > 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.uploads.create(file) .then(({ uploads }) => { console.log(uploads.length); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/uploads' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: image/jpeg' \ --form 'files=@""' \ --form 'files=@""' security: - api_token: [] - cookie_auth: [] tags: - Upload responses: '200': description: OK content: application/json: schema: properties: uploads: type: array items: type: object properties: url: type: string description: The URL of the uploaded file. format: uri '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /users: post: operationId: PostUsers summary: Create a User description: Creates a User x-authenticated: true requestBody: content: application/json: schema: required: - email - password properties: email: description: The Users email. type: string format: email first_name: description: The name of the User. type: string last_name: description: The name of the User. type: string role: description: Userrole assigned to the user. type: string enum: - admin - member - developer password: description: The Users password. type: string format: password x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.create({ email: 'user@example.com', password: 'supersecret' }) .then(({ user }) => { console.log(user.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/users' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com", "password": "supersecret" }' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetUsers summary: List Users description: Retrieves all users. x-authenticated: true x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.list() .then(({ users }) => { console.log(users.length); }); - lang: Shell label: cURL source: | curl --location --request GET 'https://medusa-url.com/admin/users' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: users: type: array items: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' '/users/{id}': delete: operationId: DeleteUsersUser summary: Delete a User description: Deletes a User x-authenticated: true parameters: - in: path name: id required: true description: The ID of the User. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.delete(user_id) .then(({ id, object, deleted }) => { console.log(id); }); - lang: Shell label: cURL source: > curl --location --request DELETE 'https://medusa-url.com/admin/users/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: id: type: string description: The ID of the deleted user. object: type: string description: The type of the object that was deleted. default: user deleted: type: boolean description: Whether or not the items were deleted. default: true '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' get: operationId: GetUsersUser summary: Get a User description: Retrieves a User. x-authenticated: true parameters: - in: path name: id required: true description: The ID of the User. schema: type: string x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.retrieve(user_id) .then(({ user }) => { console.log(user.id); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/users/{id}' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' post: operationId: PostUsersUser summary: Update a User description: Updates a User parameters: - in: path name: id required: true description: The ID of the User. schema: type: string x-authenticated: true requestBody: content: application/json: schema: properties: first_name: description: The name of the User. type: string last_name: description: The name of the User. type: string role: description: Userrole assigned to the user. type: string enum: - admin - member - developer api_token: description: The api token of the User. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.update(user_id, { first_name: 'Marcellus' }) .then(({ user }) => { console.log(user.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/users/{id}' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Marcellus" }' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /users/password-token: post: operationId: PostUsersUserPasswordToken summary: Request Password Reset description: Generates a password token for a User with a given email. x-authenticated: true requestBody: content: application/json: schema: required: - email properties: email: description: The Users email. type: string format: email x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.sendResetPasswordToken({ email: 'user@example.com' }) .then(() => { // successful }) .catch(() => { // error occurred }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/users/password-token' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "user@example.com" }' security: - api_token: [] - cookie_auth: [] tags: - User responses: '204': description: OK '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /users/reset-password: post: operationId: PostUsersUserPassword summary: Reset Password description: Sets the password for a User given the correct token. x-authenticated: true requestBody: content: application/json: schema: required: - token - password properties: email: description: The Users email. type: string format: email token: description: The token generated from the 'password-token' endpoint. type: string password: description: The Users new password. type: string format: password x-codeSamples: - lang: JavaScript label: JS Client source: > 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.users.resetPassword({ token: 'supersecrettoken', password: 'supersecret' }) .then(({ user }) => { console.log(user.id); }); - lang: Shell label: cURL source: > curl --location --request POST 'https://medusa-url.com/admin/users/reset-password' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "token": "supersecrettoken", "password": "supersecret" }' security: - api_token: [] - cookie_auth: [] tags: - User responses: '200': description: OK content: application/json: schema: properties: user: $ref: '#/components/schemas/user' '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' /variants: get: operationId: GetVariants summary: List Product Variants description: Retrieves a list of Product Variants x-authenticated: true parameters: - in: query name: id description: A Product Variant id to filter by. schema: type: string - in: query name: ids description: A comma separated list of Product Variant ids to filter by. schema: type: string - in: query name: expand description: A comma separated list of Product Variant relations to load. schema: type: string - in: query name: fields description: A comma separated list of Product Variant fields to include. schema: type: string - in: query name: offset description: How many product variants to skip in the result. schema: type: number default: '0' - in: query name: limit description: Maximum number of Product Variants to return. schema: type: number default: '100' - in: query name: cart_id description: The id of the cart to use for price selection. schema: type: string - in: query name: region_id description: The id of the region to use for price selection. schema: type: string - in: query name: currency_code description: The currency code to use for price selection. schema: type: string - in: query name: customer_id description: The id of the customer to use for price selection. schema: type: string - in: query name: title style: form explode: false description: product variant title to search for. schema: oneOf: - type: string description: a single title to search by - type: array description: multiple titles to search by items: type: string - in: query name: inventory_quantity description: Filter by available inventory quantity schema: oneOf: - type: number description: a specific number to search by. - type: object description: search using less and greater than comparisons. properties: lt: type: number description: filter by inventory quantity less than this number gt: type: number description: filter by inventory quantity greater than this number lte: type: number description: >- filter by inventory quantity less than or equal to this number gte: type: number description: >- filter by inventory quantity greater than or equal to this number x-codeSamples: - lang: JavaScript label: JS Client source: > 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.variants.list() .then(({ variants, limit, offset, count }) => { console.log(variants.length); }); - lang: Shell label: cURL source: > curl --location --request GET 'https://medusa-url.com/admin/variants' \ --header 'Authorization: Bearer {api_token}' security: - api_token: [] - cookie_auth: [] tags: - Product Variant responses: '200': description: OK content: application/json: schema: properties: variants: type: array items: $ref: '#/components/schemas/product_variant' count: type: integer description: The total number of items available offset: type: integer description: The number of items skipped before these items limit: type: integer description: The number of items per page '400': $ref: '#/components/responses/400_error' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found_error' '409': $ref: '#/components/responses/invalid_state_error' '422': $ref: '#/components/responses/invalid_request_error' '500': $ref: '#/components/responses/500_error' components: responses: default_error: description: Default Error content: application/json: schema: $ref: '#/components/schemas/error' example: code: unknown_error message: An unknown error occurred. type: unknown_error invalid_state_error: description: Invalid State Error content: application/json: schema: $ref: '#/components/schemas/error' example: code: unknown_error message: >- The request conflicted with another request. You may retry the request with the provided Idempotency-Key. type: QueryRunnerAlreadyReleasedError invalid_request_error: description: Invalid Request Error content: application/json: schema: $ref: '#/components/schemas/error' example: code: invalid_request_error message: Discount with code TEST already exists. type: duplicate_error not_found_error: description: Not Found Error content: application/json: schema: $ref: '#/components/schemas/error' example: message: Entity with id 1 was not found type: not_found 400_error: description: Client Error or Multiple Errors content: application/json: schema: oneOf: - $ref: '#/components/schemas/error' - $ref: '#/components/schemas/multiple_errors' examples: not_allowed: $ref: '#/components/examples/not_allowed_error' invalid_data: $ref: '#/components/examples/invalid_data_error' multiple_errors: $ref: '#/components/examples/multiple_errors' 500_error: description: Server Error content: application/json: schema: $ref: '#/components/schemas/error' examples: database: $ref: '#/components/examples/database_error' unexpected_state: $ref: '#/components/examples/unexpected_state_error' invalid_argument: $ref: '#/components/examples/invalid_argument_error' default_error: $ref: '#/components/examples/default_error' unauthorized: description: User is not authorized. Must log in first content: text/plain: schema: type: string default: Unauthorized example: Unauthorized incorrect_credentials: description: User does not exist or incorrect credentials content: text/plain: schema: type: string default: Unauthorized example: Unauthorized examples: not_allowed_error: summary: Not Allowed Error value: message: Discount must be set to dynamic type: not_allowed invalid_data_error: summary: Invalid Data Error value: message: first_name must be a string type: invalid_data multiple_errors: summary: Multiple Errors value: message: >- Provided request body contains errors. Please check the data and retry the request errors: - message: first_name must be a string type: invalid_data - message: Discount must be set to dynamic type: not_allowed database_error: summary: Database Error value: code: api_error message: An error occured while hashing password type: database_error unexpected_state_error: summary: Unexpected State Error value: message: cart.total must be defined type: unexpected_state invalid_argument_error: summary: Invalid Argument Error value: message: cart.total must be defined type: unexpected_state default_error: summary: Default Error value: code: unknown_error message: An unknown error occurred. type: unknown_error securitySchemes: api_token: type: http x-displayName: API Token description: > 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: ```bash psql -d -U UPDATE public.user SET api_token='' WHERE email=''; ``` Where: - `` is the name of the database schema you use for the Medusa server. - `` is the name of the user that has privileges over the database schema. - `` is the API token you want to associate with the user. You can use [this tool to generate a random token](https://randomkeygen.com/). - `` 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 alternatively following along with the JS Client request samples, you must provide the `apiKey` option when creating the Medusa client: ```js const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3, apiKey: '{api_token}' }) ``` scheme: bearer cookie_auth: type: apiKey in: cookie name: connect.sid x-displayName: Cookie Session ID description: > Use a cookie session to send authenticated requests. ### How to Obtain the Cookie Session 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 admin user 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 user](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`: ```bash curl -v --location --request POST 'https://medusa-url.com/admin/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: ```bash 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: ```bash curl --location --request GET 'https://medusa-url.com/admin/products' \ --header 'Cookie: connect.sid={sid}' ``` Where `{sid}` is the value of `connect.sid` that you copied. schemas: address_fields: title: Address Fields description: Address fields used when creating/updating an address. x-resourceId: address properties: company: type: string description: Company name example: Acme first_name: type: string description: First name example: Arno last_name: type: string description: Last name example: Willms address_1: type: string description: Address line 1 example: 14433 Kemmer Court address_2: type: string description: Address line 2 example: Suite 369 city: type: string description: City example: South Geoffreyview country_code: type: string description: The 2 character ISO code of the country in lower case externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements description: See a list of codes. example: st province: type: string description: Province example: Kentucky postal_code: type: string description: Postal Code example: 72093 phone: type: string description: Phone Number example: 16128234334802 metadata: type: object description: An optional key-value map with additional details example: car: white address: title: Address description: An address. x-resourceId: address properties: id: type: string description: ID of the address example: addr_01G8ZC9VS1XVE149MGH2J7QSSH customer_id: type: string description: ID of the customer this address belongs to example: cus_01G2SG30J8C85S4A5CHM2S1NS2 customer: description: Available if the relation `customer` is expanded. type: array items: type: object description: A customer object. company: type: string description: Company name example: Acme first_name: type: string description: First name example: Arno last_name: type: string description: Last name example: Willms address_1: type: string description: Address line 1 example: 14433 Kemmer Court address_2: type: string description: Address line 2 example: Suite 369 city: type: string description: City example: South Geoffreyview country_code: type: string description: The 2 character ISO code of the country in lower case externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements description: See a list of codes. example: st country: description: A country object. Available if the relation `country` is expanded. type: object province: type: string description: Province example: Kentucky postal_code: type: string description: Postal Code example: 72093 phone: type: string description: Phone Number example: 16128234334802 created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white batch_job: title: Batch Job description: A Batch Job. x-resourceId: batch_job required: - type properties: id: type: string description: The unique identifier for the batch job. example: batch_01G8T782965PYFG0751G0Z38B4 type: type: string description: The type of batch job. enum: - product-import - product-export status: type: string description: The status of the batch job. enum: - created - pre_processed - confirmed - processing - completed - canceled - failed default: created created_by: type: string description: The unique identifier of the user that created the batch job. example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V created_by_user: description: >- A user object. Available if the relation `created_by_user` is expanded. type: object context: type: object description: >- The context of the batch job, the type of the batch job determines what the context should contain. 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 dry_run: type: boolean description: Specify if the job must apply the modifications or not. default: false result: type: object description: The result of the batch job. properties: count: type: number advancement_count: type: number progress: type: number errors: type: object properties: message: type: string code: oneOf: - type: string - type: number err: type: array stat_descriptors: type: object properties: key: type: string name: type: string message: type: string file_key: type: string file_size: type: number example: 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: type: string description: The date from which the job has been pre processed. format: date-time processing_at: type: string description: The date the job is processing at. format: date-time confirmed_at: type: string description: The date when the confirmation has been done. format: date-time completed_at: type: string description: The date of the completion. format: date-time canceled_at: type: string description: The date of the concellation. format: date-time failed_at: type: string description: The date when the job failed. format: date-time created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was last updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time cart: title: Cart description: Represents a user cart x-resourceId: cart properties: id: type: string description: The cart's ID example: cart_01G8ZH853Y6TFXWPG5EYE81X63 email: type: string description: The email associated with the cart format: email billing_address_id: type: string description: The billing address's ID example: addr_01G8ZH853YPY9B94857DY91YGW billing_address: description: Available if the relation `billing_address` is expanded. $ref: '#/components/schemas/address' shipping_address_id: type: string description: The shipping address's ID example: addr_01G8ZH853YPY9B94857DY91YGW shipping_address: description: Available if the relation `shipping_address` is expanded. $ref: '#/components/schemas/address' items: description: Available if the relation `items` is expanded. type: array items: $ref: '#/components/schemas/line_item' region_id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object discounts: type: array description: Available if the relation `discounts` is expanded. items: type: object description: A discount object. gift_cards: type: array description: Available if the relation `gift_cards` is expanded. items: type: object description: A gift card object. customer_id: type: string description: The customer's ID example: cus_01G2SG30J8C85S4A5CHM2S1NS2 customer: description: A customer object. Available if the relation `customer` is expanded. type: object payment_session: description: The selected payment session in the cart. $ref: '#/components/schemas/payment_session' payment_sessions: type: array description: The payment sessions created on the cart. items: $ref: '#/components/schemas/payment_session' payment_id: type: string description: The payment's ID if available example: pay_01G8ZCC5W42ZNY842124G7P5R9 payment: description: Available if the relation `payment` is expanded. $ref: '#/components/schemas/payment' shipping_methods: type: array description: The shipping methods added to the cart. items: $ref: '#/components/schemas/shipping_method' type: type: string description: The cart's type. enum: - default - swap - draft_order - payment_link - claim default: default completed_at: type: string description: The date with timezone at which the cart was completed. format: date-time payment_authorized_at: type: string description: The date with timezone at which the payment was authorized. format: date-time idempotency_key: type: string description: >- Randomly generated key used to continue the completion of a cart in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. context: type: object description: >- The context of the cart which can include info like IP or user agent. example: ip: '::1' user_agent: PostmanRuntime/7.29.2 sales_channel_id: type: string description: The sales channel ID the cart is associated with. example: null sales_channel: description: >- A sales channel object. Available if the relation `sales_channel` is expanded. type: object created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white shipping_total: type: integer description: The total of shipping example: 1000 discount_total: type: integer description: The total of discount example: 800 tax_total: type: integer description: The total of tax example: 0 refunded_total: type: integer description: >- The total amount refunded if the order associated with this cart is returned. example: 0 total: type: integer description: The total amount of the cart example: 8200 subtotal: type: integer description: The subtotal of the cart example: 8000 refundable_amount: type: integer description: The amount that can be refunded example: 8200 gift_card_total: type: integer description: The total of gift cards example: 0 gift_card_tax_total: type: integer description: The total of gift cards with taxes example: 0 claim_image: title: Claim Image description: Represents photo documentation of a claim. x-resourceId: claim_image required: - claim_item_id - url properties: id: type: string description: The claim image's ID example: cimg_01G8ZH853Y6TFXWPG5EYE81X63 claim_item_id: type: string description: The ID of the claim item associated with the image claim_item: description: >- A claim item object. Available if the relation `claim_item` is expanded. type: object url: type: string description: The URL of the image format: uri created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white claim_item: title: Claim Item description: >- Represents a claimed item along with information about the reasons for the claim. x-resourceId: claim_item required: - claim_order_id - item_id - variant_id - reason - quantity properties: id: type: string description: The claim item's ID example: citm_01G8ZH853Y6TFXWPG5EYE81X63 images: type: array description: Available if the relation `images` is expanded. items: $ref: '#/components/schemas/claim_image' claim_order_id: description: The ID of the claim this item is associated with. type: string claim_order: description: >- A claim order object. Available if the relation `claim_order` is expanded. type: object item_id: description: The ID of the line item that the claim item refers to. type: string example: item_01G8ZM25TN49YV9EQBE2NC27KC item: description: Available if the relation `item` is expanded. $ref: '#/components/schemas/line_item' variant_id: description: The ID of the product variant that is claimed. type: string example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6 variant: description: A variant object. Available if the relation `variant` is expanded. type: object reason: description: The reason for the claim type: string enum: - missing_item - wrong_item - production_failure - other note: description: 'An optional note about the claim, for additional information' type: string example: I don't like it. quantity: description: >- The quantity of the item that is being claimed; must be less than or equal to the amount purchased in the original order. type: integer example: 1 tags: description: >- User defined tags for easy filtering and grouping. Available if the relation 'tags' is expanded. type: array items: $ref: '#/components/schemas/claim_tag' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white claim_order: title: Claim Order description: >- Claim Orders represent a group of faulty or missing items. Each claim order consists of a subset of items associated with an original order, and can contain additional information about fulfillments and returns. x-resourceId: claim_order required: - type - order_id properties: id: type: string description: The claim's ID example: claim_01G8ZH853Y6TFXWPG5EYE81X63 type: type: string enum: - refund - replace payment_status: type: string description: The status of the claim's payment enum: - na - not_refunded - refunded default: na fulfillment_status: type: string enum: - not_fulfilled - partially_fulfilled - fulfilled - partially_shipped - shipped - partially_returned - returned - canceled - requires_action default: not_fulfilled claim_items: description: The items that have been claimed type: array items: $ref: '#/components/schemas/claim_item' additional_items: description: >- Refers to the new items to be shipped when the claim order has the type `replace` type: array items: $ref: '#/components/schemas/line_item' order_id: description: The ID of the order that the claim comes from. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object return_order: description: >- A return object. Holds information about the return if the claim is to be returned. Available if the relation 'return_order' is expanded type: object shipping_address_id: description: The ID of the address that the new items should be shipped to type: string example: addr_01G8ZH853YPY9B94857DY91YGW shipping_address: description: Available if the relation `shipping_address` is expanded. $ref: '#/components/schemas/address' shipping_methods: description: The shipping methods that the claim order will be shipped with. type: array items: $ref: '#/components/schemas/shipping_method' fulfillments: description: The fulfillments of the new items to be shipped type: array items: $ref: '#/components/schemas/fulfillment' refund_amount: description: The amount that will be refunded in conjunction with the claim type: integer example: 1000 canceled_at: description: The date with timezone at which the claim was canceled. type: string format: date-time created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white no_notification: description: >- Flag for describing whether or not notifications related to this should be send. type: boolean example: false idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the cart associated with the claim in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. claim_tag: title: Claim Tag description: >- Claim Tags are user defined tags that can be assigned to claim items for easy filtering and grouping. x-resourceId: claim_tag required: - value properties: id: type: string description: The claim tag's ID example: ctag_01G8ZCC5Y63B95V6B5SHBZ91S4 value: description: The value that the claim tag holds type: string example: Damaged created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white country: title: Country description: Country details x-resourceId: country required: - iso_2 - iso_3 - num_code - name - display_name properties: id: type: string description: The country's ID example: 109 iso_2: type: string description: The 2 character ISO code of the country in lower case example: it externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements description: See a list of codes. iso_3: type: string description: The 2 character ISO code of the country in lower case example: ita externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements description: See a list of codes. num_code: description: The numerical ISO code for the country. type: string example: 380 externalDocs: url: >- https://en.wikipedia.org/wiki/ISO_3166-1_numeric#Officially_assigned_code_elements description: See a list of codes. name: description: The normalized country name in upper case. type: string example: ITALY display_name: description: The country name appropriate for display. type: string example: Italy region_id: type: string description: The region ID this country is associated with. example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object currency: title: Currency description: Currency x-resourceId: currency required: - code - symbol - symbol_native - name properties: code: description: The 3 character ISO code for the currency. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. symbol: description: The symbol used to indicate the currency. type: string example: $ symbol_native: description: The native symbol used to indicate the currency. type: string example: $ name: description: The written name of the currency type: string example: US Dollar includes_tax: description: '[EXPERIMENTAL] Does the currency prices include tax' type: boolean custom_shipping_option: title: Custom Shipping Option description: >- Custom Shipping Options are 'overriden' Shipping Options. Store managers can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option x-resourceId: custom_shipping_option required: - price - shipping_option_id properties: id: type: string description: The custom shipping option's ID example: cso_01G8X99XNB77DMFBJFWX6DN9V9 price: description: >- The custom price set that will override the shipping option's original price type: integer example: 1000 shipping_option_id: description: >- The ID of the Shipping Option that the custom shipping option overrides type: string example: so_01G1G5V27GYX4QXNARRQCW1N8T shipping_option: description: >- A shipping option object. Available if the relation `shipping_option` is expanded. type: object cart_id: description: The ID of the Cart that the custom shipping option is attached to type: string example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white includes_tax: description: >- [EXPERIMENTAL] Indicates if the custom shipping option price include tax type: boolean customer_group: title: Customer Group description: Represents a customer group x-resourceId: customer_group required: - name properties: id: type: string description: The customer group's ID example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63 name: type: string description: The name of the customer group example: VIP customers: type: array description: >- The customers that belong to the customer group. Available if the relation `customers` is expanded. items: type: object description: A customer object. price_lists: type: array description: >- The price lists that are associated with the customer group. Available if the relation `price_lists` is expanded. items: $ref: '#/components/schemas/price_list' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white customer: title: Customer description: Represents a customer x-resourceId: customer required: - email properties: id: type: string description: The customer's ID example: cus_01G2SG30J8C85S4A5CHM2S1NS2 email: type: string description: The customer's email format: email first_name: type: string description: The customer's first name example: Arno last_name: type: string description: The customer's first name example: Willms billing_address_id: type: string description: The customer's billing address ID example: addr_01G8ZH853YPY9B94857DY91YGW billing_address: description: Available if the relation `billing_address` is expanded. $ref: '#/components/schemas/address' shipping_addresses: description: Available if the relation `shipping_addresses` is expanded. type: array items: $ref: '#/components/schemas/address' phone: type: string description: The customer's phone number example: 16128234334802 has_account: type: boolean description: Whether the customer has an account or not default: false orders: description: Available if the relation `orders` is expanded. type: array items: type: object description: An order object. groups: description: >- The customer groups the customer belongs to. Available if the relation `groups` is expanded. type: array items: $ref: '#/components/schemas/customer_group' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition_customer_group: title: Product Tag Discount Condition description: Associates a discount condition with a customer group x-resourceId: discount_condition_customer_group required: - customer_group_id - condition_id properties: customer_group_id: description: The ID of the Product Tag type: string example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63 condition_id: description: The ID of the Discount Condition type: string example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A customer_group: description: Available if the relation `customer_group` is expanded. $ref: '#/components/schemas/customer_group' discount_condition: description: Available if the relation `discount_condition` is expanded. $ref: '#/components/schemas/discount_condition' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition_product_collection: title: Product Collection Discount Condition description: Associates a discount condition with a product collection x-resourceId: discount_condition_product_collection required: - product_collection_id - condition_id properties: product_collection_id: description: The ID of the Product Collection type: string example: pcol_01F0YESBFAZ0DV6V831JXWH0BG condition_id: description: The ID of the Discount Condition type: string example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A product_collection: description: Available if the relation `product_collection` is expanded. $ref: '#/components/schemas/product_collection' discount_condition: description: Available if the relation `discount_condition` is expanded. $ref: '#/components/schemas/discount_condition' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition_product_tag: title: Product Tag Discount Condition description: Associates a discount condition with a product tag x-resourceId: discount_condition_product_tag required: - product_tag_id - condition_id properties: product_tag_id: description: The ID of the Product Tag type: string example: ptag_01F0YESHPZYY3H4SJ3A5918SBN condition_id: description: The ID of the Discount Condition type: string example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A product_tag: description: Available if the relation `product_tag` is expanded. $ref: '#/components/schemas/product_tag' discount_condition: description: Available if the relation `discount_condition` is expanded. $ref: '#/components/schemas/discount_condition' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition_product_type: title: Product Type Discount Condition description: Associates a discount condition with a product type x-resourceId: discount_condition_product required: - product_type_id - condition_id properties: product_type_id: description: The ID of the Product Tag type: string example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A condition_id: description: The ID of the Discount Condition type: string example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A product_type: description: Available if the relation `product_type` is expanded. $ref: '#/components/schemas/product_type' discount_condition: description: Available if the relation `discount_condition` is expanded. $ref: '#/components/schemas/discount_condition' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition_product: title: Product Discount Condition description: Associates a discount condition with a product x-resourceId: discount_condition_product required: - product_id - condition_id properties: product_id: description: The ID of the Product Tag type: string example: prod_01G1G5V2MBA328390B5AXJ610F condition_id: description: The ID of the Discount Condition type: string example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A product: description: Available if the relation `product` is expanded. $ref: '#/components/schemas/product' discount_condition: description: Available if the relation `discount_condition` is expanded. $ref: '#/components/schemas/discount_condition' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_condition: title: Discount Condition description: Holds rule conditions for when a discount is applicable x-resourceId: discount_condition required: - type - operator - discount_rule_id properties: id: type: string description: The discount condition's ID example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A type: description: The type of the Condition type: string enum: - products - product_types - product_collections - product_tags - customer_groups operator: description: The operator of the Condition type: string enum: - in - not_in discount_rule_id: type: string description: The ID of the discount rule associated with the condition example: dru_01F0YESMVK96HVX7N419E3CJ7C discount_rule: description: Available if the relation `discount_rule` is expanded. $ref: '#/components/schemas/discount_rule' products: description: >- products associated with this condition if type = products. Available if the relation `products` is expanded. type: array items: type: object description: A product object. product_types: description: >- product types associated with this condition if type = product_types. Available if the relation `product_types` is expanded. type: array items: type: object description: A product type object. product_tags: description: >- product tags associated with this condition if type = product_tags. Available if the relation `product_tags` is expanded. type: array items: type: object description: A product tag object. product_collections: description: >- product collections associated with this condition if type = product_collections. Available if the relation `product_collections` is expanded. type: array items: type: object description: A product collection object. customer_groups: description: >- customer groups associated with this condition if type = customer_groups. Available if the relation `customer_groups` is expanded. type: array items: type: object description: A customer group object. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount_rule: title: Discount Rule description: >- Holds the rules that governs how a Discount is calculated when applied to a Cart. x-resourceId: discount_rule required: - type - value properties: id: type: string description: The discount rule's ID example: dru_01F0YESMVK96HVX7N419E3CJ7C type: description: >- The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers. type: string enum: - fixed - percentage - free_shipping example: percentage description: description: A short description of the discount type: string example: 10 Percent value: description: >- The value that the discount represents; this will depend on the type of the discount type: integer example: 10 allocation: description: The scope that the discount should apply to. type: string enum: - total - item example: total conditions: description: >- A set of conditions that can be used to limit when the discount can be used. Available if the relation `conditions` is expanded. type: array items: type: object description: A discount condition object. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white discount: title: Discount description: >- Represents a discount that can be applied to a cart for promotional purposes. x-resourceId: discount required: - code - is_dynamic properties: id: type: string description: The discount's ID example: disc_01F0YESMW10MGHWJKZSDDMN0VN code: description: >- A unique code for the discount - this will be used by the customer to apply the discount type: string example: 10DISC is_dynamic: description: >- A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts type: boolean example: false rule_id: type: string description: The Discount Rule that governs the behaviour of the Discount example: dru_01F0YESMVK96HVX7N419E3CJ7C rule: description: Available if the relation `rule` is expanded. $ref: '#/components/schemas/discount_rule' is_disabled: description: >- Whether the Discount has been disabled. Disabled discounts cannot be applied to carts type: boolean example: false parent_discount_id: type: string description: >- The Discount that the discount was created from. This will always be a dynamic discount example: disc_01G8ZH853YPY9B94857DY91YGW parent_discount: description: Available if the relation `parent_discount` is expanded. $ref: '#/components/schemas/discount' starts_at: description: The time at which the discount can be used. type: string format: date-time ends_at: description: The time at which the discount can no longer be used. type: string format: date-time valid_duration: type: string description: Duration the discount runs between example: P3Y6M4DT12H30M5S regions: description: >- The Regions in which the Discount can be used. Available if the relation `regions` is expanded. type: array items: type: object description: A region object. usage_limit: description: The maximum number of times that a discount can be used. type: integer example: 100 usage_count: description: The number of times a discount has been used. type: integer example: 50 default: 0 created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white draft-order: title: DraftOrder description: Represents a draft order x-resourceId: draft-order properties: id: type: string description: The draft order's ID example: dorder_01G8TJFKBG38YYFQ035MSVG03C status: type: string description: The status of the draft order enum: - open - completed default: open display_id: type: string description: The draft order's display ID example: 2 cart_id: type: string description: The ID of the cart associated with the draft order. example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object order_id: type: string description: The ID of the order associated with the draft order. example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object canceled_at: type: string description: The date the draft order was canceled at. format: date-time completed_at: type: string description: The date the draft order was completed at. format: date-time no_notification_order: type: boolean description: Whether to send the customer notifications regarding order updates. example: false idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white fulfillment_item: title: Fulfillment Item description: >- Correlates a Line Item with a Fulfillment, keeping track of the quantity of the Line Item. x-resourceId: fulfillment_item required: - fulfillment_id - item_id - quantity properties: fulfillment_id: description: The id of the Fulfillment that the Fulfillment Item belongs to. type: string example: ful_01G8ZRTMQCA76TXNAT81KPJZRF item_id: description: The id of the Line Item that the Fulfillment Item references. type: string example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN fulfillment: description: >- A fulfillment object. Available if the relation `fulfillment` is expanded. type: object item: description: Available if the relation `item` is expanded. $ref: '#/components/schemas/line_item' quantity: description: The quantity of the Line Item that is included in the Fulfillment. type: integer example: 1 fulfillment_provider: title: Fulfillment Provider description: >- Represents a fulfillment provider plugin and holds its installation status. x-resourceId: fulfillment_provider properties: id: description: The id of the fulfillment provider as given by the plugin. type: string example: manual is_installed: description: >- Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`. type: boolean example: true fulfillment: title: Fulfillment description: >- Fulfillments are created once store operators can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a provider, which is typically an external shipping aggregator, shipping partner og 3PL, most plugins will have asynchronous communications with these providers through webhooks in order to automatically update and synchronize the state of Fulfillments. x-resourceId: fulfillment required: - provider_id properties: id: type: string description: The cart's ID example: ful_01G8ZRTMQCA76TXNAT81KPJZRF claim_order_id: description: The id of the Claim that the Fulfillment belongs to. type: string example: null claim_order: description: >- A claim order object. Available if the relation `claim_order` is expanded. type: object swap_id: description: The id of the Swap that the Fulfillment belongs to. type: string example: null swap: description: A swap object. Available if the relation `swap` is expanded. type: object order_id: description: The id of the Order that the Fulfillment belongs to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object provider_id: description: >- The id of the Fulfillment Provider responsible for handling the fulfillment type: string example: manual provider: description: Available if the relation `provider` is expanded. $ref: '#/components/schemas/fulfillment_provider' items: description: >- The Fulfillment Items in the Fulfillment - these hold information about how many of each Line Item has been fulfilled. Available if the relation `items` is expanded. type: array items: $ref: '#/components/schemas/fulfillment_item' tracking_links: description: >- The Tracking Links that can be used to track the status of the Fulfillment, these will usually be provided by the Fulfillment Provider. Available if the relation `tracking_links` is expanded. type: array items: $ref: '#/components/schemas/tracking_link' tracking_numbers: deprecated: true description: >- The tracking numbers that can be used to track the status of the fulfillment. type: array items: type: string data: description: >- This contains all the data necessary for the Fulfillment provider to handle the fulfillment. type: object example: {} shipped_at: description: The date with timezone at which the Fulfillment was shipped. type: string format: date-time no_notification: description: >- Flag for describing whether or not notifications related to this should be send. type: boolean example: false canceled_at: description: The date with timezone at which the Fulfillment was canceled. type: string format: date-time idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the fulfillment in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white gift_card_transaction: title: Gift Card Transaction description: >- Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order x-resourceId: gift_card_transaction required: - gift_card_id - amount properties: id: type: string description: The gift card transaction's ID example: gct_01G8X9A7ESKAJXG2H0E6F1MW7A gift_card_id: description: The ID of the Gift Card that was used in the transaction. type: string example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ gift_card: description: >- A gift card object. Available if the relation `gift_card` is expanded. type: object order_id: description: The ID of the Order that the Gift Card was used to pay for. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object amount: description: The amount that was used from the Gift Card. type: integer example: 10 created_at: description: The date with timezone at which the resource was created. type: string format: date-time is_taxable: description: Whether the transaction is taxable or not. type: boolean example: false tax_rate: description: The tax rate of the transaction type: number example: 0 gift_card: title: Gift Card description: >- Gift Cards are redeemable and represent a value that can be used towards the payment of an Order. x-resourceId: gift_card required: - code - value - balance - region_id properties: id: type: string description: The cart's ID example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ code: description: >- The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card. type: string example: 3RFT-MH2C-Y4YZ-XMN4 value: description: The value that the Gift Card represents. type: integer example: 10 balance: description: The remaining value on the Gift Card. type: integer example: 10 region_id: type: string description: The id of the Region in which the Gift Card is available. example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object order_id: type: string description: The id of the Order that the Gift Card was purchased in. example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object is_disabled: description: >- Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts. type: boolean example: false ends_at: description: The time at which the Gift Card can no longer be used. type: string format: date-time created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white idempotency_key: title: Idempotency Key description: >- Idempotency Key is used to continue a process in case of any failure that might occur. x-resourceId: idempotency_key required: - idempotency_key properties: id: type: string description: The idempotency key's ID example: ikey_01G8X9A7ESKAJXG2H0E6F1MW7A idempotency_key: description: >- The unique randomly generated key used to determine the state of a process. type: string externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: description: Date which the idempotency key was locked. type: string format: date-time locked_at: description: Date which the idempotency key was locked. type: string format: date-time request_method: description: The method of the request type: string example: POST request_params: type: object description: The parameters passed to the request example: id: cart_01G8ZH853Y6TFXWPG5EYE81X63 request_path: description: The request's path type: string example: /store/carts/cart_01G8ZH853Y6TFXWPG5EYE81X63/complete response_code: type: string description: The response's code. example: 200 response_body: type: object description: The response's body example: id: cart_01G8ZH853Y6TFXWPG5EYE81X63 recovery_point: type: string description: Where to continue from. default: started image: title: Image description: Images holds a reference to a URL at which the image file can be found. x-resourceId: image required: - url properties: id: type: string description: The image's ID example: img_01G749BFYR6T8JTVW6SGW3K3E6 url: description: The URL at which the image file can be found. type: string format: uri created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white invite: title: Invite description: Represents an invite x-resourceId: invite required: - user_email properties: id: type: string description: The invite's ID example: invite_01G8TKE4XYCTHSCK2GDEP47RE1 user_email: type: string description: The email of the user being invited. format: email role: type: string description: The user's role. enum: - admin - member - developer default: member accepted: type: boolean description: Whether the invite was accepted or not. example: false token: type: string description: The token used to accept the invite. expores_at: type: string description: The date the invite expires at. format: date-time created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white line_item_adjustment: title: Line Item Adjustment description: Represents an Line Item Adjustment x-resourceId: line_item_adjustment required: - item_id - description - amount properties: id: type: string description: The invite's ID example: lia_01G8TKE4XYCTHSCK2GDEP47RE1 item_id: type: string description: The ID of the line item example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN item: description: Available if the relation `item` is expanded. $ref: '#/components/schemas/line_item' description: type: string description: The line item's adjustment description example: Adjusted item's price. discount_id: type: string description: The ID of the discount associated with the adjustment example: disc_01F0YESMW10MGHWJKZSDDMN0VN discount: description: Available if the relation `discount` is expanded. $ref: '#/components/schemas/discount' amount: type: number description: The adjustment amount example: 1000 metadata: type: object description: An optional key-value map with additional details example: car: white line_item_tax_line: title: Line Item Tax Line description: Represents an Line Item Tax Line x-resourceId: line_item_tax_line required: - item_id - rate - name properties: id: type: string description: The line item tax line's ID example: litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8 item_id: type: string description: The ID of the line item example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN item: description: Available if the relation `item` is expanded. $ref: '#/components/schemas/line_item' code: description: A code to identify the tax type by type: string example: tax01 name: description: A human friendly name for the tax type: string example: Tax Example rate: description: The numeric rate to charge tax by type: number example: 10 created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white line_item: title: Line Item description: >- Line Items represent purchasable units that can be added to a Cart for checkout. When Line Items are purchased they will get copied to the resulting order and can eventually be referenced in Fulfillments and Returns. Line Items may also be created when processing Swaps and Claims. x-resourceId: line_item required: - title - unit_price - quantity properties: id: type: string description: The cart's ID example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN cart_id: description: The ID of the Cart that the Line Item belongs to. type: string example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object order_id: description: The ID of the Order that the Line Item belongs to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object swap_id: description: The id of the Swap that the Line Item belongs to. type: string example: null swap: description: A swap object. Available if the relation `swap` is expanded. type: object claim_order_id: description: The id of the Claim that the Line Item belongs to. type: string example: null claim_order: description: >- A claim order object. Available if the relation `claim_order` is expanded. type: object tax_lines: description: Available if the relation `tax_lines` is expanded. type: array items: $ref: '#/components/schemas/line_item_tax_line' adjustments: description: Available if the relation `adjustments` is expanded. type: array items: $ref: '#/components/schemas/line_item_adjustment' title: description: >- The title of the Line Item, this should be easily identifiable by the Customer. type: string example: Medusa Coffee Mug description: description: A more detailed description of the contents of the Line Item. type: string example: One Size thumbnail: description: A URL string to a small image of the contents of the Line Item. type: string format: uri example: >- https://medusa-public-images.s3.eu-west-1.amazonaws.com/coffee-mug.png is_return: description: Is the item being returned type: boolean example: false is_giftcard: description: Flag to indicate if the Line Item is a Gift Card. type: boolean example: false should_merge: description: >- Flag to indicate if new Line Items with the same variant should be merged or added as an additional Line Item. type: boolean example: false allow_discounts: description: >- Flag to indicate if the Line Item should be included when doing discount calculations. type: boolean example: false has_shipping: description: >- Flag to indicate if the Line Item has fulfillment associated with it. type: boolean example: false unit_price: description: >- The price of one unit of the content in the Line Item. This should be in the currency defined by the Cart/Order/Swap/Claim that the Line Item belongs to. type: boolean example: 8000 variant_id: description: The id of the Product Variant contained in the Line Item. type: string example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6 variant: description: >- A product variant object. The Product Variant contained in the Line Item. Available if the relation `variant` is expanded. type: object quantity: description: The quantity of the content in the Line Item. type: integer example: 1 fulfilled_quantity: description: The quantity of the Line Item that has been fulfilled. type: integer example: 0 returned_quantity: description: The quantity of the Line Item that has been returned. type: integer example: 0 shipped_quantity: description: The quantity of the Line Item that has been shipped. type: integer example: 0 refundable: description: >- The amount that can be refunded from the given Line Item. Takes taxes and discounts into consideration. type: integer example: 0 subtotal: type: integer description: The subtotal of the line item example: 8000 tax_total: type: integer description: The total of tax of the line item example: 0 total: type: integer description: The total amount of the line item example: 8000 original_total: type: integer description: The original total amount of the line item example: 8000 original_tax_total: type: integer description: The original tax total amount of the line item example: 0 discount_total: type: integer description: The total of discount of the line item example: 0 gift_card_total: type: integer description: The total of the gift card of the line item example: 0 includes_tax: description: '[EXPERIMENTAL] Indicates if the line item unit_price include tax' type: boolean original_item_id: description: '[EXPERIMENTAL] The id of the original line item' type: string order_edit_id: description: >- [EXPERIMENTAL] The ID of the order edit to which a cloned item belongs type: string order_edit: description: '[EXPERIMENTAL] The order edit joined' type: object created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white money_amount: title: Money Amount description: >- Money Amounts represents an amount that a given Product Variant can be purcased for. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used the amount will be in the currency defined for the Reigon. x-resourceId: money_amount required: - currency_code - amount properties: id: type: string description: The money amount's ID example: ma_01F0YESHRFQNH5S8Q0PK84YYZN currency_code: description: The 3 character currency code that the Money Amount is given in. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currency: description: Available if the relation `currency` is expanded. $ref: '#/components/schemas/currency' amount: description: >- The amount in the smallest currecny unit (e.g. cents 100 cents to charge $1) that the Product Variant will cost. type: integer example: 100 min_quantity: description: >- The minimum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities. type: integer example: 1 max_quantity: description: >- The maximum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities. type: integer example: 1 price_list_id: type: string description: The ID of the price list associated with the money amount example: pl_01G8X3CKJXCG5VXVZ87H9KC09W price_list: description: Available if the relation `price_list` is expanded. $ref: '#/components/schemas/price_list' variant_id: description: The id of the Product Variant contained in the Line Item. type: string example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6 variant: description: >- The Product Variant contained in the Line Item. Available if the relation `variant` is expanded. type: object region_id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white note: title: Note description: >- Notes are elements which we can use in association with different resources to allow users to describe additional information in relation to these. x-resourceId: note required: - value - resource_type - resource_id properties: id: type: string description: The note's ID example: note_01G8TM8ENBMC7R90XRR1G6H26Q resource_type: description: The type of resource that the Note refers to. type: string example: order resource_id: description: The ID of the resource that the Note refers to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK value: description: The contents of the note. type: string example: This order must be fulfilled on Monday author_id: type: string description: The ID of the author (user) example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V author: description: Available if the relation `author` is expanded. $ref: '#/components/schemas/user' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white notification_provider: title: Notification Provider description: >- Represents a notification provider plugin and holds its installation status. x-resourceId: notification_provider required: - id properties: id: description: The id of the notification provider as given by the plugin. type: string example: sendgrid is_installed: description: >- Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`. type: boolean default: true notification: title: Notification description: >- Notifications a communications sent via Notification Providers as a reaction to internal events such as `order.placed`. Notifications can be used to show a chronological timeline for communications sent to a Customer regarding an Order, and enables resends. x-resourceId: notification required: - resource_type - resource_id - to properties: id: type: string description: The notification's ID example: noti_01G53V9Y6CKMCGBM1P0X7C28RX event_name: description: The name of the event that the notification was sent for. type: string example: order.placed resource_type: description: The type of resource that the Notification refers to. type: string example: order resource_id: description: The ID of the resource that the Notification refers to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK customer_id: description: The ID of the Customer that the Notification was sent to. type: string example: cus_01G2SG30J8C85S4A5CHM2S1NS2 customer: description: A customer object. Available if the relation `customer` is expanded. type: object to: description: >- The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id type: string example: user@example.com data: description: >- The data that the Notification was sent with. This contains all the data necessary for the Notification Provider to initiate a resend. type: object example: {} resends: description: >- The resends that have been completed after the original Notification. type: array items: $ref: '#/components/schemas/notification_resend' provider_id: description: The id of the Notification Provider that handles the Notification. type: string example: sengrid provider: description: Available if the relation `provider` is expanded. $ref: '#/components/schemas/notification_provider' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time notification_resend: title: Notification Resend description: A resend of a Notification. x-resourceId: notification_resend properties: id: description: The notification resend's ID type: string example: noti_01F0YET45G9NHP08Z66CE4QKBS event_name: description: The name of the event that the notification was sent for. type: string example: order.placed resource_type: description: The type of resource that the Notification refers to. type: string example: order resource_id: description: The ID of the resource that the Notification refers to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK customer_id: description: The ID of the Customer that the Notification was sent to. type: string example: cus_01G2SG30J8C85S4A5CHM2S1NS2 customer: description: A customer object. Available if the relation `customer` is expanded. type: object to: description: >- The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id type: string example: user@example.com data: description: >- The data that the Notification was sent with. This contains all the data necessary for the Notification Provider to initiate a resend. type: object example: {} parent_id: description: The ID of the Notification that was originally sent. type: string example: noti_01G53V9Y6CKMCGBM1P0X7C28RX parent_notification: description: Available if the relation `parent_notification` is expanded. $ref: '#/components/schemas/notification' provider_id: description: The ID of the Notification Provider that handles the Notification. type: string example: sengrid provider: description: Available if the relation `provider` is expanded. $ref: '#/components/schemas/notification_provider' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time OAuth: title: OAuth description: Represent an OAuth app x-resourceId: OAuth required: - id - display_name - application_name properties: id: type: string description: The app's ID example: example_app display_name: type: string description: The app's display name example: Example app application_name: type: string description: The app's name example: example install_url: type: string description: The URL to install the app format: uri uninstall_url: type: string description: The URL to uninstall the app format: uri data: type: object description: Any data necessary to the app. example: {} order_edit: title: Order Edit description: Order edit keeps track of order items changes. x-resourceId: order_edit required: - order_id - order - changes - created_by properties: id: type: string description: The order edit's ID example: oe_01G8TJSYT9M6AVS5N4EMNFS1EK order_id: type: string description: The ID of the order that is edited example: order_01G2SG30J8C85S4A5CHM2S1NS2 order: description: Available if the relation `order` is expanded. $ref: '#/components/schemas/order' changes: type: array description: Available if the relation `changes` is expanded. items: $ref: '#/components/schemas/order_item_change' internal_note: description: An optional note with additional details about the order edit. type: string example: Included two more items B to the order. created_by: type: string description: >- The unique identifier of the user or customer who created the order edit. requested_by: type: string description: >- The unique identifier of the user or customer who requested the order edit. requested_at: type: string description: The date with timezone at which the edit was requested. format: date-time confirmed_by: type: string description: >- The unique identifier of the user or customer who confirmed the order edit. confirmed_at: type: string description: The date with timezone at which the edit was confirmed. format: date-time declined_by: type: string description: >- The unique identifier of the user or customer who declined the order edit. declined_at: type: string description: The date with timezone at which the edit was declined. format: date-time declined_reason: description: An optional note why the order edit is declined. type: string subtotal: type: integer description: The total of subtotal example: 8000 discount_total: type: integer description: The total of discount example: 800 shipping_total: type: integer description: The total of the shipping amount example: 800 gift_card_total: type: integer description: The total of the gift card amount example: 800 gift_card_tax_total: type: integer description: The total of the gift card tax amount example: 800 tax_total: type: integer description: The total of tax example: 0 total: type: integer description: The total amount of the edited order. example: 8200 difference_due: type: integer description: >- The difference between the total amount of the order and total amount of edited order. example: 8200 status: type: string description: The status of the order edit. enum: - confirmed - declined - requested - created - canceled items: type: array description: Available if the relation `items` is expanded. items: $ref: '#/components/schemas/line_item' payment_collection_id: type: string description: The ID of the payment collection example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK payment_collection: description: Available if the relation `payment_collection` is expanded. $ref: '#/components/schemas/payment_collection' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time order_item_change: title: Order Item Change description: Represents an order edit item change x-resourceId: order_item_change required: - type - order_edit_id properties: id: type: string description: The order item change's ID example: oic_01G8TJSYT9M6AVS5N4EMNFS1EK type: type: string description: The order item change's status enum: - item_add - item_remove - item_update order_edit_id: type: string description: The ID of the order edit example: oe_01G2SG30J8C85S4A5CHM2S1NS2 order_edit: description: Available if the relation `order_edit` is expanded. $ref: '#/components/schemas/order_edit' original_line_item_id: type: string description: The ID of the original line item in the order example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN original_line_item: description: Available if the relation `original_line_item` is expanded. $ref: '#/components/schemas/line_item' line_item_id: type: string description: The ID of the cloned line item. example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN line_item: description: Available if the relation `line_item` is expanded. $ref: '#/components/schemas/line_item' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white order: title: Order description: Represents an order x-resourceId: order required: - customer_id - email - region_id - currency_code properties: id: type: string description: The order's ID example: order_01G8TJSYT9M6AVS5N4EMNFS1EK status: type: string description: The order's status enum: - pending - completed - archived - canceled - requires_action default: pending fulfillment_status: type: string description: The order's fulfillment status enum: - not_fulfilled - partially_fulfilled - fulfilled - partially_shipped - shipped - partially_returned - returned - canceled - requires_action default: not_fulfilled payment_status: type: string description: The order's payment status enum: - not_paid - awaiting - captured - partially_refunded - refuneded - canceled - requires_action default: not_paid display_id: type: integer description: The order's display ID example: 2 cart_id: type: string description: The ID of the cart associated with the order example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object customer_id: type: string description: The ID of the customer associated with the order example: cus_01G2SG30J8C85S4A5CHM2S1NS2 customer: description: A customer object. Available if the relation `customer` is expanded. type: object email: description: The email associated with the order type: string format: email billing_address_id: type: string description: The ID of the billing address associated with the order example: addr_01G8ZH853YPY9B94857DY91YGW billing_address: description: Available if the relation `billing_address` is expanded. $ref: '#/components/schemas/address' shipping_address_id: type: string description: The ID of the shipping address associated with the order example: addr_01G8ZH853YPY9B94857DY91YGW shipping_address: description: Available if the relation `shipping_address` is expanded. $ref: '#/components/schemas/address' region_id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object currency_code: description: The 3 character currency code that is used in the order type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currency: description: Available if the relation `currency` is expanded. $ref: '#/components/schemas/currency' tax_rate: description: The order's tax rate type: number example: 0 discounts: type: array description: >- The discounts used in the order. Available if the relation `discounts` is expanded. items: type: object description: A discount object. gift_cards: type: array description: >- The gift cards used in the order. Available if the relation `gift_cards` is expanded. items: type: object description: A gift card object. shipping_methods: type: array description: >- The shipping methods used in the order. Available if the relation `shipping_methods` is expanded. items: $ref: '#/components/schemas/shipping_method' payments: type: array description: >- The payments used in the order. Available if the relation `payments` is expanded. items: $ref: '#/components/schemas/payment' fulfillments: type: array description: >- The fulfillments used in the order. Available if the relation `fulfillments` is expanded. items: $ref: '#/components/schemas/fulfillment' returns: type: array description: >- The returns associated with the order. Available if the relation `returns` is expanded. items: type: object description: A return object. claims: type: array description: >- The claims associated with the order. Available if the relation `claims` is expanded. items: type: object description: A claim order object. refunds: type: array description: >- The refunds associated with the order. Available if the relation `refunds` is expanded. items: type: object description: A refund object. swaps: type: array description: >- The swaps associated with the order. Available if the relation `swaps` is expanded. items: type: object description: A swap object. draft_order_id: type: string description: The ID of the draft order this order is associated with. example: null draft_order: description: >- A draft order object. Available if the relation `draft_order` is expanded. type: object items: type: array description: >- The line items that belong to the order. Available if the relation `items` is expanded. items: $ref: '#/components/schemas/line_item' edits: type: array description: >- [EXPERIMENTAL] Order edits done on the order. Available if the relation `edits` is expanded. items: $ref: '#/components/schemas/order_edit' gift_card_transactions: type: array description: >- The gift card transactions used in the order. Available if the relation `gift_card_transactions` is expanded. items: $ref: '#/components/schemas/gift_card_transaction' canceled_at: type: string description: The date the order was canceled on. format: date-time no_notification: description: >- Flag for describing whether or not notifications related to this should be send. type: boolean example: false idempotency_key: type: string description: >- Randomly generated key used to continue the processing of the order in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. external_id: description: The ID of an external order. type: string example: null sales_channel_id: type: string description: The ID of the sales channel this order is associated with. example: null sales_channel: description: >- A sales channel object. Available if the relation `sales_channel` is expanded. type: object shipping_total: type: integer description: The total of shipping example: 1000 discount_total: type: integer description: The total of discount example: 800 tax_total: type: integer description: The total of tax example: 0 refunded_total: type: integer description: The total amount refunded if the order is returned. example: 0 total: type: integer description: The total amount of the order example: 8200 subtotal: type: integer description: The subtotal of the order example: 8000 paid_total: type: integer description: The total amount paid example: 8000 refundable_amount: type: integer description: The amount that can be refunded example: 8200 gift_card_total: type: integer description: The total of gift cards example: 0 gift_card_tax_total: type: integer description: The total of gift cards with taxes example: 0 payment_collection: title: Payment Collection description: Payment Collection x-resourceId: payment_collection required: - type - status - amount - region_id - currency_code - created_by properties: id: type: string description: The payment collection's ID example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK type: type: string description: The type of the payment collection enum: - order_edit status: type: string description: The type of the payment collection enum: - not_paid - awaiting - authorized - partially_authorized - captured - partially_captured - refunded - partially_refunded - canceled - requires_action description: type: string description: Description of the payment collection amount: type: number description: Amount of the payment collection. authorized_amount: type: number description: Authorized amount of the payment collection. captured_amount: type: number description: Captured amount of the payment collection. refunded_amount: type: number description: Refunded amount of the payment collection. region_id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: Available if the relation `region` is expanded. $ref: '#/components/schemas/region' currency_code: description: The 3 character ISO code for the currency. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currency: description: Available if the relation `currency` is expanded. $ref: '#/components/schemas/currency' payment_sessions: type: array description: Available if the relation `payment_sessions` is expanded. items: $ref: '#/components/schemas/payment_session' payments: type: array description: Available if the relation `payments` is expanded. items: $ref: '#/components/schemas/payment' created_by: type: string description: The ID of the user that created the payment collection. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white payment_provider: title: Payment Provider description: Represents a Payment Provider plugin and holds its installation status. x-resourceId: payment_provider required: - id properties: id: description: The id of the payment provider as given by the plugin. type: string example: manual is_installed: description: >- Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`. type: boolean default: true payment_session: title: Payment Session description: >- 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. x-resourceId: payment_session required: - cart_id - provider_id - status properties: id: type: string description: The payment session's ID example: ps_01G901XNSRM2YS3ASN9H5KG3FZ cart_id: description: The id of the Cart that the Payment Session is created for. type: string example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object provider_id: description: >- The id of the Payment Provider that is responsible for the Payment Session type: string example: manual is_selected: description: >- A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase. type: boolean example: true status: description: >- 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. type: string enum: - authorized - pending - requires_more - error - canceled example: pending data: description: >- 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. type: object example: {} idempotency_key: type: string description: >- Randomly generated key used to continue the completion of a cart in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time payment: title: Payment description: >- Payments represent an amount authorized with a given payment method, Payments can be captured, canceled or refunded. x-resourceId: payment required: - amount - currency_code - provider_id properties: id: type: string description: The payment's ID example: pay_01G2SJNT6DEEWDFNAJ4XWDTHKE swap_id: description: The ID of the Swap that the Payment is used for. type: string example: null swap: description: A swap object. Available if the relation `swap` is expanded. type: object cart_id: description: The id of the Cart that the Payment Session is created for. type: string cart: description: A cart object. Available if the relation `cart` is expanded. type: object order_id: description: The ID of the Order that the Payment is used for. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object amount: description: The amount that the Payment has been authorized for. type: integer example: 100 currency_code: description: The 3 character ISO currency code that the Payment is completed in. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currency: description: Available if the relation `currency` is expanded. $ref: '#/components/schemas/currency' amount_refunded: description: >- The amount of the original Payment amount that has been refunded back to the Customer. type: integer example: 0 provider_id: description: The id of the Payment Provider that is responsible for the Payment type: string example: manual data: description: >- The data required for the Payment Provider to identify, modify and process the Payment. 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. type: object example: {} captured_at: description: The date with timezone at which the Payment was captured. type: string format: date-time canceled_at: description: The date with timezone at which the Payment was canceled. type: string format: date-time idempotency_key: type: string description: >- Randomly generated key used to continue the completion of a payment in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white price_list: title: Price List description: >- Price Lists represents a set of prices that overrides the default price for one or more product variants. x-resourceId: price_list required: - name - description properties: id: type: string description: The price list's ID example: pl_01G8X3CKJXCG5VXVZ87H9KC09W name: type: string description: The price list's name example: VIP Prices description: type: string description: The price list's description example: Prices for VIP customers type: description: >- The type of Price List. This can be one of either `sale` or `override`. type: string enum: - sale - override default: sale status: description: The status of the Price List type: string enum: - active - draft default: draft starts_at: description: The date with timezone that the Price List starts being valid. type: string format: date-time ends_at: description: The date with timezone that the Price List stops being valid. type: string format: date-time customer_groups: description: >- The Customer Groups that the Price List applies to. Available if the relation `customer_groups` is expanded. type: array items: type: object description: A customer group object. prices: description: >- The Money Amounts that are associated with the Price List. Available if the relation `prices` is expanded. type: array items: oneOf: - $ref: '#/components/schemas/money_amount' - $ref: '#/components/schemas/customer_group' includes_tax: description: '[EXPERIMENTAL] Does the price list prices include tax' type: boolean created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time product_collection: title: Product Collection description: Product Collections represents a group of Products that are related. x-resourceId: product_collection required: - title properties: id: type: string description: The product collection's ID example: pcol_01F0YESBFAZ0DV6V831JXWH0BG title: description: The title that the Product Collection is identified by. type: string example: Summer Collection handle: description: >- A unique string that identifies the Product Collection - can for example be used in slug structures. type: string example: summer-collection products: description: >- The Products contained in the Product Collection. Available if the relation `products` is expanded. type: array items: type: object description: A product collection object. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_option_value: title: Product Option Value description: >- A value given to a Product Variant's option set. Product Variant have a Product Option Value for each of the Product Options defined on the Product. x-resourceId: product_option_value required: - value - option_id - variant_id properties: id: type: string description: The product option value's ID example: optval_01F0YESHR7S6ECD03RF6W12DSJ value: description: >- The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is "Size" this value could be "Small", "Medium" or "Large"). type: string example: large option_id: description: >- The ID of the Product Option that the Product Option Value is defined for. type: string example: opt_01F0YESHQBZVKCEXJ24BS6PCX3 option: description: Available if the relation `option` is expanded. $ref: '#/components/schemas/product_option' variant_id: description: >- The ID of the Product Variant that the Product Option Value is defined for. type: string example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6 variant: description: Available if the relation `variant` is expanded. $ref: '#/components/schemas/product_variant' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_option: title: Product Option description: >- Product Options define properties that may vary between different variants of a Product. Common Product Options are "Size" and "Color", but Medusa doesn't limit what Product Options that can be defined. x-resourceId: product_option required: - title - product_id properties: id: type: string description: The product option's ID example: opt_01F0YESHQBZVKCEXJ24BS6PCX3 title: description: The title that the Product Option is defined by (e.g. "Size"). type: string example: Size values: description: >- The Product Option Values that are defined for the Product Option. Available if the relation `values` is expanded. type: array items: $ref: '#/components/schemas/product_option_value' product_id: description: The ID of the Product that the Product Option is defined for. type: string example: prod_01G1G5V2MBA328390B5AXJ610F product: description: A product object. Available if the relation `product` is expanded. type: object created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_tag: title: Product Tag description: Product Tags can be added to Products for easy filtering and grouping. x-resourceId: product_tag required: - value properties: id: type: string description: The product tag's ID example: ptag_01G8K2MTMG9168F2B70S1TAVK3 value: description: The value that the Product Tag represents type: string example: Pants created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_tax_rate: title: Product Tax Rate description: >- Associates a tax rate with a product to indicate that the product is taxed in a certain way x-resourceId: product_tax_rate required: - product_id - rate_id properties: product_id: description: The ID of the Product type: string example: prod_01G1G5V2MBA328390B5AXJ610F product: description: Available if the relation `product` is expanded. $ref: '#/components/schemas/product' rate_id: description: The ID of the Tax Rate type: string example: txr_01G8XDBAWKBHHJRKH0AV02KXBR tax_rate: description: Available if the relation `tax_rate` is expanded. $ref: '#/components/schemas/tax_rate' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_type_tax_rate: title: Product Type Tax Rate description: >- Associates a tax rate with a product type to indicate that the product type is taxed in a certain way x-resourceId: product_type_tax_rate required: - product_type_id - rate_id properties: product_type_id: description: The ID of the Product type type: string example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A product_type: description: Available if the relation `product_type` is expanded. $ref: '#/components/schemas/product_type' rate_id: description: The id of the Tax Rate type: string example: txr_01G8XDBAWKBHHJRKH0AV02KXBR tax_rate: description: Available if the relation `tax_rate` is expanded. $ref: '#/components/schemas/tax_rate' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_type: title: Product Type description: >- Product Type can be added to Products for filtering and reporting purposes. x-resourceId: product_type required: - value properties: id: type: string description: The product type's ID example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A value: description: The value that the Product Type represents. type: string example: Clothing created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_variant: title: Product Variant description: >- 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. x-resourceId: product_variant required: - title - product_id - inventory_quantity properties: id: type: string description: The product variant's ID example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6 title: description: >- A title that can be displayed for easy identification of the Product Variant. type: string example: Small product_id: description: The ID of the Product that the Product Variant belongs to. type: string example: prod_01G1G5V2MBA328390B5AXJ610F product: description: A product object. Available if the relation `product` is expanded. type: object prices: description: >- 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. type: array items: $ref: '#/components/schemas/money_amount' sku: description: >- 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. type: string example: shirt-123 barcode: description: >- A generic field for a GTIN number that can be used to identify the Product Variant. type: string example: null ean: description: >- An EAN barcode number that can be used to identify the Product Variant. type: string example: null upc: description: >- A UPC barcode number that can be used to identify the Product Variant. type: string example: null variant_rank: description: The ranking of this variant type: number default: 0 inventory_quantity: description: The current quantity of the item that is stocked. type: integer example: 100 allow_backorder: description: >- Whether the Product Variant should be purchasable when `inventory_quantity` is 0. type: boolean default: false manage_inventory: description: Whether Medusa should manage inventory for the Product Variant. type: boolean default: true hs_code: description: >- The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null origin_country: description: >- The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null mid_code: description: >- 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. type: string example: null material: description: >- The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null weight: description: >- The weight of the Product Variant. May be used in shipping rate calculations. type: number example: null height: description: >- The height of the Product Variant. May be used in shipping rate calculations. type: number example: null width: description: >- The width of the Product Variant. May be used in shipping rate calculations. type: number example: null length: description: >- The length of the Product Variant. May be used in shipping rate calculations. type: number example: null options: description: >- The Product Option Values specified for the Product Variant. Available if the relation `options` is expanded. type: array items: $ref: '#/components/schemas/product_option_value' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white product_variant_prices_fields: title: Product Variant Prices Fields description: Product Variants Prices Fields that are only available in some requests. x-resourceId: product_variant_prices_fields properties: original_price: type: number description: >- The original price of the variant without any discounted prices applied. calculated_price: type: number description: The calculated price of the variant. Can be a discounted price. original_price_incl_tax: type: number description: The original price of the variant including taxes. calculated_price_incl_tax: type: number description: The calculated price of the variant including taxes. original_tax: type: number description: The taxes applied on the original price. calculated_tax: type: number description: The taxes applied on the calculated price. tax_rates: type: array description: An array of applied tax rates items: type: object properties: rate: type: number description: The tax rate value name: type: string description: The name of the tax rate code: type: string description: The code of the tax rate product: title: Product description: >- 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. x-resourceId: product required: - title - profile_id properties: id: type: string description: The product's ID example: prod_01G1G5V2MBA328390B5AXJ610F title: description: >- A title that can be displayed for easy identification of the Product. type: string example: Medusa Coffee Mug subtitle: description: >- An optional subtitle that can be used to further specify the Product. type: string description: description: A short description of the Product. type: string example: Every programmer's best friend. handle: description: A unique identifier for the Product (e.g. for slug structure). type: string example: coffee-mug is_giftcard: description: >- Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased. type: boolean default: false status: description: The status of the product type: string enum: - draft - proposed - published - rejected default: draft images: description: >- Images of the Product. Available if the relation `images` is expanded. type: array items: $ref: '#/components/schemas/image' thumbnail: description: A URL to an image file that can be used to identify the Product. type: string format: uri options: description: >- 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. type: array items: $ref: '#/components/schemas/product_option' variants: description: >- 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. type: array items: $ref: '#/components/schemas/product_variant' profile_id: description: >- 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. type: string example: sp_01G1G5V239ENSZ5MV4JAR737BM profile: description: Available if the relation `profile` is expanded. $ref: '#/components/schemas/shipping_profile' weight: description: >- The weight of the Product Variant. May be used in shipping rate calculations. type: number example: null height: description: >- The height of the Product Variant. May be used in shipping rate calculations. type: number example: null width: description: >- The width of the Product Variant. May be used in shipping rate calculations. type: number example: null length: description: >- The length of the Product Variant. May be used in shipping rate calculations. type: number example: null hs_code: description: >- The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null origin_country: description: >- The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null mid_code: description: >- 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. type: string example: null material: description: >- The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers. type: string example: null collection_id: type: string description: The Product Collection that the Product belongs to example: pcol_01F0YESBFAZ0DV6V831JXWH0BG collection: description: >- A product collection object. Available if the relation `collection` is expanded. type: object type_id: type: string description: The Product type that the Product belongs to example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A type: description: Available if the relation `type` is expanded. $ref: '#/components/schemas/product_type' tags: description: >- The Product Tags assigned to the Product. Available if the relation `tags` is expanded. type: array items: $ref: '#/components/schemas/product_tag' discountable: description: >- Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to `false`. type: boolean default: true external_id: description: The external ID of the product type: string example: null sales_channels: description: >- The sales channels the product is associated with. Available if the relation `sales_channels` is expanded. type: array items: type: object description: A sales channel object. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white refund: title: Refund description: >- Refund represent an amount of money transfered back to the Customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by a store operator. x-resourceId: refund required: - order_id - amount properties: id: type: string description: The refund's ID example: ref_01G1G5V27GYX4QXNARRQCW1N8T order_id: description: The id of the Order that the Refund is related to. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK amount: description: The amount that has be refunded to the Customer. type: integer example: 1000 note: description: An optional note explaining why the amount was refunded. type: string example: I didn't like it reason: description: >- The reason given for the Refund, will automatically be set when processed as part of a Swap, Claim or Return. type: string enum: - discount - return - swap - claim - other example: return idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the refund in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white region: title: Region description: >- 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. x-resourceId: region required: - name - currency_code - tax_rate properties: id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G name: description: >- 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. type: string example: EU currency_code: description: The 3 character currency code that the Region uses. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. currency: description: Available if the relation `currency` is expanded. $ref: '#/components/schemas/currency' tax_rate: description: The tax rate that should be charged on purchases in the Region. type: number example: 0 tax_rates: description: >- The tax rates that are included in the Region. Available if the relation `tax_rates` is expanded. type: array items: $ref: '#/components/schemas/tax_rate' tax_code: description: >- The tax code used on purchases in the Region. This may be used by other systems for accounting purposes. type: string example: null gift_cards_taxable: description: Whether the gift cards are taxable or not in this region. type: boolean default: true automatic_taxes: description: Whether taxes should be automated in this region. type: boolean default: true countries: description: >- The countries that are included in the Region. Available if the relation `countries` is expanded. type: array items: $ref: '#/components/schemas/country' tax_provider_id: type: string description: The ID of the tax provider used in this region example: null tax_provider: description: Available if the relation `tax_provider` is expanded. $ref: '#/components/schemas/tax_provider' payment_providers: description: >- The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded. type: array items: $ref: '#/components/schemas/payment_provider' fulfillment_providers: description: >- The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `payment_providers` is expanded. type: array items: $ref: '#/components/schemas/fulfillment_provider' includes_tax: description: '[EXPERIMENTAL] Does the prices for the region include tax' type: boolean created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white return_item: title: Return Item description: >- Correlates a Line Item with a Return, keeping track of the quantity of the Line Item that will be returned. x-resourceId: return_item required: - return_id - item_id properties: return_id: description: The id of the Return that the Return Item belongs to. type: string example: ret_01F0YET7XPCMF8RZ0Y151NZV2V return_order: description: Available if the relation `return_order` is expanded. $ref: '#/components/schemas/return' item_id: description: The id of the Line Item that the Return Item references. type: string example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN item: description: Available if the relation `item` is expanded. $ref: '#/components/schemas/line_item' quantity: description: The quantity of the Line Item that is included in the Return. type: integer example: 1 is_requested: description: >- Whether the Return Item was requested initially or received unexpectedly in the warehouse. type: boolean default: true requested_quantity: description: The quantity that was originally requested to be returned. type: integer example: 1 recieved_quantity: description: The quantity that was received in the warehouse. type: integer example: 1 reason_id: description: The ID of the reason for returning the item. type: string example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ reason: description: Available if the relation `reason` is expanded. $ref: '#/components/schemas/return_reason' note: description: An optional note with additional details about the Return. type: string example: I didn't like it. metadata: type: object description: An optional key-value map with additional details example: car: white return_reason: title: Return Reason description: >- 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. x-resourceId: return_reason required: - value - label properties: id: type: string description: The cart's ID example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ description: description: A description of the Reason. type: string example: Items that are damaged label: description: A text that can be displayed to the Customer as a reason. type: string example: Damaged goods value: description: The value to identify the reason by. type: string example: damaged parent_return_reason_id: type: string description: The ID of the parent reason. example: null parent_return_reason: description: Available if the relation `parent_return_reason` is expanded. $ref: '#/components/schemas/return_reason' return_reason_children: description: Available if the relation `return_reason_children` is expanded. $ref: '#/components/schemas/return_reason' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white return: title: Return description: >- 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. x-resourceId: return required: - refund_amount properties: id: type: string description: The return's ID example: ret_01F0YET7XPCMF8RZ0Y151NZV2V status: description: Status of the Return. type: string enum: - requested - received - requires_action - canceled default: requested items: description: >- The Return Items that will be shipped back to the warehouse. Available if the relation `items` is expanded. type: array items: $ref: '#/components/schemas/return_item' swap_id: description: The ID of the Swap that the Return is a part of. type: string example: null swap: description: A swap object. Available if the relation `swap` is expanded. type: object order_id: description: The ID of the Order that the Return is made from. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object claim_order_id: description: The ID of the Claim that the Return is a part of. type: string example: null claim_order: description: >- A claim order object. Available if the relation `claim_order` is expanded. type: object shipping_method: description: >- The Shipping Method that will be used to send the Return back. Can be null if the Customer facilitates the return shipment themselves. Available if the relation `shipping_method` is expanded. type: array items: $ref: '#/components/schemas/shipping_method' shipping_data: description: >- Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment. type: object example: {} refund_amount: description: The amount that should be refunded as a result of the return. type: integer example: 1000 no_notification: description: >- When set to true, no notification will be sent related to this return. type: boolean example: false idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the return in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. received_at: description: The date with timezone at which the return was received. type: string format: date-time created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white sales_channel: title: Sales Channel description: A Sales Channel x-resourceId: sales_channel required: - name properties: id: type: string description: The sales channel's ID example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A name: description: The name of the sales channel. type: string example: Market description: description: The description of the sales channel. type: string example: Multi-vendor market is_disabled: description: Specify if the sales channel is enabled or disabled. type: boolean default: false created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time shipping_method_tax_line: title: Shipping Method Tax Line description: Shipping Method Tax Line x-resourceId: shipping_method_tax_line required: - shipping_method_id - rate - name properties: id: type: string description: The line item tax line's ID example: smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8 shipping_method_id: type: string description: The ID of the line item example: sm_01F0YET7DR2E7CYVSDHM593QG2 shipping_method: description: Available if the relation `shipping_method` is expanded. $ref: '#/components/schemas/shipping_method' code: description: A code to identify the tax type by type: string example: tax01 name: description: A human friendly name for the tax type: string example: Tax Example rate: description: The numeric rate to charge tax by type: number example: 10 created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white shipping_method: title: Shipping Method description: >- 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. x-resourceId: shipping_method required: - shipping_option_id - price properties: id: type: string description: The shipping method's ID example: sm_01F0YET7DR2E7CYVSDHM593QG2 shipping_option_id: description: >- The id of the Shipping Option that the Shipping Method is built from. type: string example: so_01G1G5V27GYX4QXNARRQCW1N8T shipping_option: description: Available if the relation `shipping_option` is expanded. $ref: '#/components/schemas/shipping_option' order_id: description: The id of the Order that the Shipping Method is used on. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object return_id: description: The id of the Return that the Shipping Method is used on. type: string example: null return_order: description: >- A return object. Available if the relation `return_order` is expanded. type: object swap_id: description: The id of the Swap that the Shipping Method is used on. type: string example: null swap: description: A swap object. Available if the relation `swap` is expanded. type: object cart_id: description: The id of the Cart that the Shipping Method is used on. type: string example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object claim_order_id: description: The id of the Claim that the Shipping Method is used on. type: string example: null claim_order: description: >- A claim order object. Available if the relation `claim_order` is expanded. type: object tax_lines: type: array description: Available if the relation `tax_lines` is expanded. items: $ref: '#/components/schemas/shipping_method_tax_line' price: description: >- The amount to charge for the Shipping Method. The currency of the price is defined by the Region that the Order that the Shipping Method belongs to is a part of. type: integer example: 200 data: description: >- Additional data that the Fulfillment Provider needs to fulfill the shipment. This is used in combination with the Shipping Options data, and may contain information such as a drop point id. type: object example: {} includes_tax: description: '[EXPERIMENTAL] Indicates if the shipping method price include tax' type: boolean shipping_option_requirement: title: Shipping Option Requirement description: >- A requirement that a Cart must satisfy for the Shipping Option to be available to the Cart. x-resourceId: shipping_option_requirement required: - shipping_option_id - type - amount properties: id: type: string description: The shipping option requirement's ID example: sor_01G1G5V29AB4CTNDRFSRWSRKWD shipping_option_id: description: >- The id of the Shipping Option that the hipping option requirement belongs to type: string example: so_01G1G5V27GYX4QXNARRQCW1N8T shipping_option: description: Available if the relation `shipping_option` is expanded. $ref: '#/components/schemas/shipping_option' type: description: >- The type of the requirement, this defines how the value will be compared to the Cart's total. `min_subtotal` requirements define the minimum subtotal that is needed for the Shipping Option to be available, while the `max_subtotal` defines the maximum subtotal that the Cart can have for the Shipping Option to be available. type: string enum: - min_subtotal - max_subtotal example: min_subtotal amount: description: The amount to compare the Cart subtotal to. type: integer example: 100 deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time shipping_option: title: Shipping Option description: >- Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information. x-resourceId: shipping_option required: - name - region_id - profile_id - provider_id - price_type properties: id: type: string description: The shipping option's ID example: so_01G1G5V27GYX4QXNARRQCW1N8T name: description: >- The name given to the Shipping Option - this may be displayed to the Customer. type: string example: PostFake Standard region_id: type: string description: The region's ID example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object profile_id: description: >- 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. type: string example: sp_01G1G5V239ENSZ5MV4JAR737BM profile: description: Available if the relation `profile` is expanded. $ref: '#/components/schemas/shipping_profile' provider_id: description: >- The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option. type: string example: manual provider: description: Available if the relation `provider` is expanded. $ref: '#/components/schemas/fulfillment_provider' price_type: description: >- 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. type: string enum: - flat_rate - calculated example: flat_rate amount: description: >- The amount to charge for shipping when the Shipping Option price type is `flat_rate`. type: integer example: 200 is_return: description: >- Flag to indicate if the Shipping Option can be used for Return shipments. type: boolean default: false requirements: description: >- The requirements that must be satisfied for the Shipping Option to be available for a Cart. Available if the relation `requirements` is expanded. type: array items: $ref: '#/components/schemas/shipping_option_requirement' data: description: >- The data needed for the Fulfillment Provider to identify the Shipping Option. type: object example: {} includes_tax: description: '[EXPERIMENTAL] Does the shipping option price include tax' type: boolean created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white shipping_profile: title: Shipping Profile description: >- Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products. x-resourceId: shipping_profile required: - name - type properties: id: type: string description: The shipping profile's ID example: sp_01G1G5V239ENSZ5MV4JAR737BM name: description: >- The name given to the Shipping profile - this may be displayed to the Customer. type: string example: Default Shipping Profile type: description: >- The type of the Shipping Profile, may be `default`, `gift_card` or `custom`. type: string enum: - default - gift_card - custom example: default products: description: >- The Products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded. type: array items: type: object description: A product object. shipping_options: description: >- The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation `shipping_options` is expanded. type: array items: $ref: '#/components/schemas/shipping_option' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white shipping_tax_rate: title: Shipping Tax Rate description: >- Associates a tax rate with a shipping option to indicate that the shipping option is taxed in a certain way x-resourceId: shipping_tax_rate required: - shipping_option_id - rate_id properties: shipping_option_id: description: The ID of the Shipping Option type: string example: so_01G1G5V27GYX4QXNARRQCW1N8T shipping_option: description: Available if the relation `shipping_option` is expanded. $ref: '#/components/schemas/shipping_option' rate_id: description: The ID of the Tax Rate type: string example: txr_01G8XDBAWKBHHJRKH0AV02KXBR tax_rate: description: Available if the relation `tax_rate` is expanded. $ref: '#/components/schemas/tax_rate' created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white staged_job: title: Staged Job description: A staged job resource x-resourceId: staged_job required: - event_name properties: id: type: string description: The staged job's ID example: job_01F0YET7BZTARY9MKN1SJ7AAXF event_name: description: The name of the event type: string example: order.placed data: description: Data necessary for the job type: object example: {} store: title: Store description: 'Holds settings for the Store, such as name, currencies, etc.' x-resourceId: store properties: id: type: string description: The store's ID example: store_01G1G5V21KADXNGH29BJMAJ4B4 name: description: The name of the Store - this may be displayed to the Customer. type: string example: Medusa Store default_currency_code: description: The 3 character currency code that is the default of the store. type: string example: usd externalDocs: url: 'https://en.wikipedia.org/wiki/ISO_4217#Active_codes' description: See a list of codes. default_currency: description: Available if the relation `default_currency` is expanded. $ref: '#/components/schemas/currency' currencies: description: >- The currencies that are enabled for the Store. Available if the relation `currencies` is expanded. type: array items: $ref: '#/components/schemas/currency' swap_link_template: description: >- A template to generate Swap links from. Use {{cart_id}} to include the Swap's `cart_id` in the link. type: string example: null payment_link_template: description: >- A template to generate Payment links from. Use {{cart_id}} to include the payment's `cart_id` in the link. type: string example: null invite_link_template: description: A template to generate Invite links from type: string example: null default_sales_channel_id: type: string description: The sales channel ID the cart is associated with. example: null default_sales_channel: description: >- A sales channel object. Available if the relation `default_sales_channel` is expanded. type: object metadata: type: object description: An optional key-value map with additional details example: car: white swap: title: Swap description: >- 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. x-resourceId: swap required: - fulfillment_status - payment_status - order_id properties: id: type: string description: The swap's ID example: swap_01F0YET86Y9G92D3YDR9Y6V676 fulfillment_status: description: The status of the Fulfillment of the Swap. type: string enum: - not_fulfilled - fulfilled - shipped - canceled - requires_action example: not_fulfilled payment_status: description: >- 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. type: string enum: - not_paid - awaiting - captured - confirmed - canceled - difference_refunded - partially_refunded - refunded - requires_action example: not_paid order_id: description: >- The ID of the Order where the Line Items to be returned where purchased. type: string example: order_01G8TJSYT9M6AVS5N4EMNFS1EK order: description: An order object. Available if the relation `order` is expanded. type: object additional_items: description: >- The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded. type: array items: $ref: '#/components/schemas/line_item' return_order: description: >- A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded. type: object fulfillments: description: >- The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded. type: array items: $ref: '#/components/schemas/fulfillment' payment: description: >- The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded. $ref: '#/components/schemas/payment' difference_due: description: >- 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. type: integer example: 0 shipping_address_id: description: >- The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order. type: string example: addr_01G8ZH853YPY9B94857DY91YGW shipping_address: description: Available if the relation `shipping_address` is expanded. $ref: '#/components/schemas/address' shipping_methods: description: >- The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded. type: array items: $ref: '#/components/schemas/shipping_method' cart_id: description: The id of the Cart that the Customer will use to confirm the Swap. type: string example: cart_01G8ZH853Y6TFXWPG5EYE81X63 cart: description: A cart object. Available if the relation `cart` is expanded. type: object allow_backorder: description: 'If true, swaps can be completed with items out of stock' type: boolean default: false idempotency_key: type: string description: >- Randomly generated key used to continue the completion of the swap in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. confirmed_at: description: >- The date with timezone at which the Swap was confirmed by the Customer. type: string format: date-time canceled_at: description: The date with timezone at which the Swap was canceled. type: string format: date-time no_notification: description: 'If set to true, no notification will be sent related to this swap' type: boolean example: false created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white tax_line: title: Tax Line description: Line item that specifies an amount of tax to add to a line item. x-resourceId: tax_line required: - rate - name properties: id: type: string description: The tax line's ID example: tl_01G1G5V2DRX1SK6NQQ8VVX4HQ8 code: description: A code to identify the tax type by type: string example: tax01 name: description: A human friendly name for the tax type: string example: Tax Example rate: description: The numeric rate to charge tax by type: number example: 10 created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white tax_provider: title: Tax Provider description: The tax service used to calculate taxes x-resourceId: tax_provider properties: id: description: The id of the tax provider as given by the plugin. type: string example: manual is_installed: description: >- Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`. type: boolean default: true tax_rate: title: Tax Rate description: >- A Tax Rate can be used to associate a certain rate to charge on products within a given Region x-resourceId: line_item required: - name - region_id properties: id: type: string description: The tax rate's ID example: txr_01G8XDBAWKBHHJRKH0AV02KXBR rate: description: The numeric rate to charge type: number example: 10 code: description: A code to identify the tax type by type: string example: tax01 name: description: A human friendly name for the tax type: string example: Tax Example region_id: type: string description: The id of the Region that the rate belongs to example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G region: description: A region object. Available if the relation `region` is expanded. type: object products: type: array description: >- The products that belong to this tax rate. Available if the relation `products` is expanded. items: type: object description: A product object. product_types: type: array description: >- The product types that belong to this tax rate. Available if the relation `product_types` is expanded. items: type: object description: A product type object. shipping_options: type: array description: >- The shipping options that belong to this tax rate. Available if the relation `shipping_options` is expanded. items: type: object description: A shipping option object. product_count: description: The count of products type: integer example: null product_type_count: description: The count of product types type: integer example: null shipping_option_count: description: The count of shipping options type: integer example: null created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white tracking_link: title: Tracking Link description: >- Tracking Link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment. x-resourceId: tracking_link required: - tracking_number - fulfillment_id properties: id: type: string description: The tracking link's ID example: tlink_01G8ZH853Y6TFXWPG5EYE81X63 url: description: The URL at which the status of the shipment can be tracked. type: string format: uri tracking_number: description: The tracking number given by the shipping carrier. type: string format: RH370168054CN fulfillment_id: type: string description: The id of the Fulfillment that the Tracking Link references. example: ful_01G8ZRTMQCA76TXNAT81KPJZRF fulfillment: description: Available if the relation `fulfillment` is expanded. $ref: '#/components/schemas/fulfillment' idempotency_key: type: string description: >- Randomly generated key used to continue the completion of a process in case of failure. externalDocs: url: >- https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key description: Learn more how to use the idempotency key. created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white user: title: User description: Represents a User who can manage store settings. x-resourceId: user required: - email properties: id: type: string description: The user's ID example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V email: description: The email of the User type: string format: email first_name: description: The first name of the User type: string example: Levi last_name: description: The last name of the User type: string example: Bogan api_token: description: An API token associated with the user. type: string example: null created_at: type: string description: The date with timezone at which the resource was created. format: date-time updated_at: type: string description: The date with timezone at which the resource was updated. format: date-time deleted_at: type: string description: The date with timezone at which the resource was deleted. format: date-time metadata: type: object description: An optional key-value map with additional details example: car: white multiple_errors: title: Multiple Errors x-resourceId: multiple_errors properties: errors: type: array description: Array of errors items: $ref: '#/components/schemas/error' message: type: string default: >- Provided request body contains errors. Please check the data and retry the request error: title: Response Error x-resourceId: error properties: code: type: string description: A slug code to indicate the type of the error. message: type: string description: Description of the error that occurred. type: type: string description: A slug indicating the type of the error.