Medusa Currencies API

openapi: 3.2.0
info:
  title: Medusa Currencies API
  version: 2.19.0
  description: 'Operations tagged Currencies across 2 of this provider''s published API definitions: medusa-admin-openapi.yaml, medusa-store-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Currencies
  description: 'A store can use unlimited currencies, and each region must be associated with at least one currency.


    Currencies are defined by the Currency Module. Currency API Routes allow admins to list and update currencies.'
  externalDocs:
    description: Learn more about the Currency Module
    url: https://docs.medusajs.com/resources/commerce-modules/currency
  x-associatedSchema:
    $ref: '#/components/schemas/AdminCurrency'
paths:
  /admin/currencies:
    get:
      operationId: GetCurrencies
      summary: List Currencies
      description: Retrieve a list of currencies. The currencies can be filtered by fields such as `id`. The currencies 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: q
        in: query
        description: The search term to filter the currency's searchable properties by.
        required: false
        schema:
          type: string
          title: q
          description: The search term to filter the currency's searchable properties by.
      - name: code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: code
            description: Filter by a currency code.
          - type: array
            description: Filter by currency codes.
            items:
              type: string
              title: code
              description: A currency code.
      - 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.currency.list()\n.then(({ currencies, count, limit, offset }) => {\n  console.log(currencies)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/currencies'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminCurrencyListResponse'
        '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'
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /admin/currencies/{code}:
    get:
      operationId: GetCurrenciesCode
      summary: Get a Currency
      description: Retrieve a currency by its code. You can expand the currency's relations or select the fields that should be returned using the query parameters.
      x-authenticated: true
      parameters:
      - name: code
        in: path
        description: The currency's code.
        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.currency.retrieve(\"usd\")\n.then(({ currency }) => {\n  console.log(currency)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/currencies/{code}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminCurrencyResponse'
        '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'
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /store/currencies:
    get:
      operationId: getStoreCurrencies
      summary: List Currencies
      description: Retrieve a list of currencies. The currencies can be filtered by fields such as `code`. The currencies can also be sorted or paginated.
      x-authenticated: false
      parameters:
      - name: x-publishable-api-key
        in: header
        description: Publishable API Key created in the Medusa Admin.
        required: true
        schema:
          type: string
          externalDocs:
            url: https://docs.medusajs.com/api/store#publishable-api-key
      - name: x-medusa-locale
        in: header
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      - 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: q
        in: query
        description: Search term to filter the currency's searchable properties.
        required: false
        schema:
          type: string
          title: q
          description: Search term to filter the currency's searchable properties.
      - name: code
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: code
            description: Filter by a currency code.
          - type: array
            description: Filter by currency codes.
            items:
              type: string
              title: code
              description: A currency code.
      - 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.
      - name: locale
        in: query
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/store/currencies'' \

          -H ''x-publishable-api-key: {your_publishable_api_key}'''
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCurrencyListResponse'
        '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-operation-id-source: normalized
      x-operation-id-original: GetCurrencies
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /store/currencies/{code}:
    get:
      operationId: getStoreCurrenciesByCode
      summary: Get a Currency
      description: Retrieve a currency by its code. You can expand the currency's relations or select the fields that should be returned.
      x-authenticated: false
      parameters:
      - name: code
        in: path
        description: The currency's code.
        required: true
        schema:
          type: string
      - name: x-publishable-api-key
        in: header
        description: Publishable API Key created in the Medusa Admin.
        required: true
        schema:
          type: string
          externalDocs:
            url: https://docs.medusajs.com/api/store#publishable-api-key
      - name: x-medusa-locale
        in: header
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      - 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: locale
        in: query
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/store/currencies/{code}'' \

          -H ''x-publishable-api-key: {your_publishable_api_key}'''
      tags:
      - Currencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCurrencyResponse'
        '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-operation-id-source: normalized
      x-operation-id-original: GetCurrenciesCode
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
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
    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
    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'
  schemas:
    AdminCurrencyResponse:
      type: object
      description: The currency's details.
      x-schemaName: AdminCurrencyResponse
      required:
      - currency
      properties:
        currency:
          $ref: '#/components/schemas/AdminCurrency'
    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
    AdminCurrencyListResponse:
      type: object
      description: The paginated list of currencies.
      x-schemaName: AdminCurrencyListResponse
      required:
      - limit
      - offset
      - count
      - currencies
      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 number of items.
        currencies:
          type: array
          description: The list of currencies.
          items:
            $ref: '#/components/schemas/AdminCurrency'
        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
    AdminCurrency:
      type: object
      description: The currency's currencies.
      x-schemaName: AdminCurrency
      required:
      - code
      - symbol
      - symbol_native
      - name
      - decimal_digits
      - rounding
      - created_at
      - updated_at
      - deleted_at
      properties:
        code:
          type: string
          title: code
          description: The currency's code.
          example: usd
        symbol:
          type: string
          title: symbol
          description: The currency's symbol.
          example: $
        symbol_native:
          type: string
          title: symbol_native
          description: The currency's native symbol, if different than the symbol.
          example: $
        name:
          type: string
          title: name
          description: The currency's name.
        decimal_digits:
          type: number
          title: decimal_digits
          description: The number of digits after the decimal for prices in this currency.
        rounding:
          type: number
          title: rounding
          description: The rounding percision applied on prices in this currency.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The currency's creation date.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The currency's update date.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The currency's deletion date.
    StoreCurrencyResponse:
      type: object
      description: The currency's details.
      x-schemaName: StoreCurrencyResponse
      required:
      - currency
      properties:
        currency:
          $ref: '#/components/schemas/StoreCurrency'
    StoreCurrency:
      type: object
      description: The currency's details.
      x-schemaName: StoreCurrency
      required:
      - code
      - symbol
      - symbol_native
      - name
      - decimal_digits
      - rounding
      - created_at
      - updated_at
      - deleted_at
      properties:
        code:
          type: string
          title: code
          description: The currency's code.
          example: usd
        symbol:
          type: string
          title: symbol
          description: The currency's symbol.
        symbol_native:
          type: string
          title: symbol_native
          description: The currency's symbol native.
        name:
          type: string
          title: name
          description: The currency's name.
        decimal_digits:
          type: number
          title: decimal_digits
          description: The currency's decimal digits.
        rounding:
          type: number
          title: rounding
          description: The currency's rounding.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the currency was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the currency was updated.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The date the currency was deleted.
    StoreCurrencyListResponse:
      type: object
      description: The paginated list of currencies.
      x-schemaName: StoreCurrencyListResponse
      required:
      - limit
      - offset
      - count
      - currencies
      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.
        currencies:
          type: array
          description: The list of currencies.
          items:
            $ref: '#/components/schemas/StoreCurrency'
        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
  examples:
    unexpected_state_error:
      summary: Unexpected State 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
    database_error:
      summary: Database Error
      value:
        code: api_error
        message: An error occured while hashing password
        type: database_error
    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
    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-refined-from:
- medusa-admin-openapi.yaml
- medusa-store-openapi.yaml