Medusa Price Preferences API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Admin Price Preferences API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/develop/LICENSE
  description: 'A price preference is used to specify whether tax-inclusiveness is enabled for a context, such as a region or currency code.


    These API routes allow admin users to manage whether a region or currency is tax inclusive.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Price Preferences
  description: 'A price preference is used to specify whether tax-inclusiveness is enabled for a context, such as a region or currency code.


    These API routes allow admin users to manage whether a region or currency is tax inclusive.'
  externalDocs:
    description: Learn more about tax-inclusiveness and the role of a price preference.
    url: https://docs.medusajs.com/resources/commerce-modules/pricing/tax-inclusive-pricing
  x-associatedSchema:
    $ref: '#/components/schemas/AdminPricePreference'
paths:
  /admin/price-preferences:
    get:
      operationId: GetPricePreferences
      summary: List Price Preferences
      description: Retrieve a list of price preferences. The price preferences can be filtered by fields such as `id`. The price preferences can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by a price preference ID.
          - type: array
            description: Filter by price preference IDs.
            items:
              type: string
              title: id
              description: A price preference ID.
      - name: attribute
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: attribute
            description: Filter by a price preference's attribute.
          - type: array
            description: Filter by price preference attributes.
            items:
              type: string
              title: attribute
              description: A price preference's attribute.
      - name: value
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: value
            description: Filter by a price preference's value.
          - type: array
            description: Filter by price preference values.
            items:
              type: string
              title: value
              description: A price preference's value.
      - name: q
        in: query
        description: Search term to apply on the price preference's searchable properties.
        required: false
        schema:
          type: string
          title: q
          description: Search term to apply on the price preference's searchable properties.
      - name: $and
        in: query
        description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $and
      - name: $or
        in: query
        description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $or
      - name: with_deleted
        in: query
        description: Whether to include deleted records in the result.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: Whether to include deleted records in the result.
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.pricePreference.list()\n.then(({ price_preferences, count, limit, offset }) => {\n  console.log(price_preferences)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/price-preferences'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Price Preferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPricePreferenceListResponse'
        '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: PostPricePreferences
      summary: Create Price Preference
      description: Create a price preference.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreatePricePreference'
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.pricePreference.create({\n  attribute: \"region_id\",\n  value: \"region_123\",\n  is_tax_inclusive: true\n})\n.then(({ price_preference }) => {\n  console.log(price_preference)\n})"
      - lang: Shell
        label: cURL
        source: 'curl -X POST ''{backend_url}/admin/price-preferences'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Price Preferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPricePreferenceResponse'
        '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'
      x-workflow: createPricePreferencesWorkflow
      x-events: []
  /admin/price-preferences/{id}:
    get:
      operationId: GetPricePreferencesId
      summary: Get a Price Preference
      description: Retrieve a price preference by its ID. You can expand the price preference's relations or select the fields that should be returned.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The price preference's ID.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.pricePreference.retrieve(\"prpref_123\")\n.then(({ price_preference }) => {\n  console.log(price_preference)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/price-preferences/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Price Preferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPricePreferenceResponse'
        '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: PostPricePreferencesId
      summary: Update a Price Preference
      description: Update a price preference's details.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The price preference's ID.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdatePricePreference'
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.pricePreference.update(\"prpref_123\", {\n  is_tax_inclusive: true\n})\n.then(({ price_preference }) => {\n  console.log(price_preference)\n})"
      - lang: Shell
        label: cURL
        source: 'curl -X POST ''{backend_url}/admin/price-preferences/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Price Preferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPricePreferenceResponse'
        '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'
      x-workflow: updatePricePreferencesWorkflow
      x-events: []
    delete:
      operationId: DeletePricePreferencesId
      summary: Delete a Price Preference
      description: Delete a price preference.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The price preference's ID.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.pricePreference.delete(\"prpref_123\")\n.then(({ deleted }) => {\n  console.log(deleted)\n})"
      - lang: Shell
        label: cURL
        source: 'curl -X DELETE ''{backend_url}/admin/price-preferences/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Price Preferences
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPricePreferenceDeleteResponse'
        '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'
      x-workflow: deletePricePreferencesWorkflow
      x-events: []
components:
  responses:
    400_error:
      description: Client Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_allowed:
              $ref: '#/components/examples/not_allowed_error'
            invalid_data:
              $ref: '#/components/examples/invalid_data_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
    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
    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'
    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
    unauthorized:
      description: User is not authorized. Must log in first
      content:
        text/plain:
          schema:
            type: string
            default: Unauthorized
            example: Unauthorized
  schemas:
    AdminPricePreferenceListResponse:
      type: object
      description: The paginated list of price preferences.
      x-schemaName: AdminPricePreferenceListResponse
      required:
      - limit
      - offset
      - count
      - price_preferences
      properties:
        limit:
          type: number
          title: limit
          description: The maximum number of items returned.
        offset:
          type: number
          title: offset
          description: The number of items skipped before retrieving the returned items.
        count:
          type: number
          title: count
          description: The total count of items.
        price_preferences:
          type: array
          description: The list of price preferences.
          items:
            $ref: '#/components/schemas/AdminPricePreference'
        estimate_count:
          type: number
          title: estimate_count
          description: The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
          x-featureFlag: index_engine
    AdminPricePreferenceResponse:
      type: object
      description: The price preference's details.
      x-schemaName: AdminPricePreferenceResponse
      required:
      - price_preference
      properties:
        price_preference:
          $ref: '#/components/schemas/AdminPricePreference'
    AdminPricePreference:
      type: object
      description: The price preference's details.
      x-schemaName: AdminPricePreference
      required:
      - id
      - attribute
      - value
      - is_tax_inclusive
      - created_at
      - updated_at
      - deleted_at
      properties:
        id:
          type: string
          title: id
          description: The price preference's ID.
        attribute:
          type: string
          title: attribute
          description: The price preference's attribute.
          example: region_id
        value:
          type: string
          title: value
          description: The price preference's value.
          example: reg_123
        is_tax_inclusive:
          type: boolean
          title: is_tax_inclusive
          description: Whether prices matching this preference include taxes.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the price preference was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the price preference was updated.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The date the price preference was deleted.
    AdminPricePreferenceDeleteResponse:
      type: object
      description: The details of the deleted price preference.
      x-schemaName: AdminPricePreferenceDeleteResponse
      required:
      - id
      - object
      - deleted
      properties:
        id:
          type: string
          title: id
          description: The price preference's ID.
        object:
          type: string
          title: object
          description: The name of the deleted object.
          default: price_preference
        deleted:
          type: boolean
          title: deleted
          description: Whether the price preference was deleted.
    Error:
      title: Response Error
      type: object
      properties:
        code:
          type: string
          description: A slug code to indicate the type of the error.
          enum:
          - invalid_state_error
          - invalid_request_error
          - api_error
          - unknown_error
        message:
          type: string
          description: Description of the error that occurred.
          example: first_name must be a string
        type:
          type: string
          description: A slug indicating the type of the error.
          enum:
          - QueryRunnerAlreadyReleasedError
          - TransactionAlreadyStartedError
          - TransactionNotStartedError
          - conflict
          - unauthorized
          - payment_authorization_error
          - duplicate_error
          - not_allowed
          - invalid_data
          - not_found
          - database_error
          - unexpected_state
          - invalid_argument
          - unknown_error
    AdminCreatePricePreference:
      type: object
      description: The price preference's details.
      x-schemaName: AdminCreatePricePreference
      properties:
        attribute:
          type: string
          title: attribute
          description: The name of the attribute the price preference applies on.
          example: currency_code
        value:
          type: string
          title: value
          description: The attribute's value.
          example: usd
        is_tax_inclusive:
          type: boolean
          title: is_tax_inclusive
          description: Whether the price is tax inclusive if the value of the specified attribute matches the specified value.
      required:
      - value
      - attribute
    AdminUpdatePricePreference:
      type: object
      description: The details to update in the price preference.
      x-schemaName: AdminUpdatePricePreference
      properties:
        attribute:
          type: string
          title: attribute
          description: The price preference's attribute.
          example: region_id
        value:
          type: string
          title: value
          description: The price preference's value.
          example: reg_123
        is_tax_inclusive:
          type: boolean
          title: is_tax_inclusive
          description: Whether prices are tax inclusive for this price preference.
  examples:
    database_error:
      summary: Database Error
      value:
        code: api_error
        message: An error occured while hashing password
        type: database_error
    default_error:
      summary: Default Error
      value:
        code: unknown_error
        message: An unknown error occurred.
        type: unknown_error
    invalid_data_error:
      summary: Invalid Data Error
      value:
        message: first_name must be a string
        type: invalid_data
    not_allowed_error:
      summary: Not Allowed Error
      value:
        message: Discount must be set to dynamic
        type: not_allowed
    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
  securitySchemes:
    api_token:
      type: http
      x-displayName: API Token
      scheme: basic
    jwt_token:
      type: http
      x-displayName: JWT Token
      scheme: bearer
    cookie_auth:
      type: apiKey
      in: cookie
      name: connect.sid
      x-displayName: Cookie Session ID
    reset_password:
      type: http
      x-displayName: Reset Password Token
      scheme: bearer
      x-is-auth: false
x-provenance:
  method: harvested
  publisher: Medusa
  source: https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/admin/openapi.full.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)