openapi: 3.1.0
info:
  title: Currencies Introduction
  description: |

    In your store, you can display prices to customers in their local currency. You can configure up to ten currencies per store.

    Configure currencies only for the locales in which you do business, and select one of the currencies to be the default currency. If a default currency is not selected, the store uses the United States Dollar (USD).

    After a customer selects a locale, the product prices in the catalog, carts, and orders are displayed in the currency for that locale. Order totals and taxes are calculated in the same currency. You cannot have a cart or order where product prices are in mixed currencies.
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  license:
    name: MIT
    url: assets/LICENSE
  version: 26.0225.7248250
  x-version-timestamp: 2026-02-25T21:31:11Z
servers:
  - url: https://useast.api.elasticpath.com
    description: US East Production Server
    variables: {}
  - url: https://euwest.api.elasticpath.com
    description: EU West Production Server
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: Currencies
    description: |
      :::caution

      - There is a hard limit of 10 currencies per store.

      :::
paths:
  /v2/currencies:
    get:
      tags:
        - Currencies
      summary: Get all Currencies
      description: |
        Fetch all currencies.
      operationId: getAllCurrencies
      parameters:
        - name: page[offset]
          in: query
          description: The number of records to offset the results by.
          style: form
          explode: true
          schema:
            type: string
            example: '0'
        - name: page[limit]
          in: query
          description: The number of records per page.
          style: form
          explode: true
          schema:
            type: string
            example: '10'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response.Data'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Response.Currency'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 400
                    title: Bad Request
                    detail: The request was invalid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 401
                    title: Unauthorized
      deprecated: false
    post:
      tags:
        - Currencies
      summary: Create a Currency
      description: |
        Create a currency.
      operationId: createACurrency
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Request.CreateCurrencies'
                - example:
                    - data:
                        code: GBP
                        decimal_places: 2
                        decimal_point: .
                        default: true
                        enabled: true
                        exchange_rate: 1
                        format: £{price}
                        thousand_separator: ','
                        type: currency
            examples:
              GBP:
                value:
                  data:
                    code: GBP
                    decimal_places: 2
                    decimal_point: .
                    default: true
                    enabled: true
                    exchange_rate: 1
                    format: £{price}
                    thousand_separator: ','
                    type: currency
              USD:
                value:
                  data:
                    code: USD
                    decimal_places: 2
                    decimal_point: .
                    default: true
                    enabled: true
                    exchange_rate: 1
                    format: ${price}
                    thousand_separator: ','
                    type: currency
        required: false
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response.Data'
                  - properties:
                      data:
                        $ref: '#/components/schemas/Response.Currency'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 400
                    title: Currency already exists
                    detail: The specified currency code already exists
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 422
                    title: Currency limit reached
                    detail: You have reached the maximum allowed currency limit of 10
      deprecated: false
    parameters: []
  /v2/currencies/{currencyID}:
    get:
      tags:
        - Currencies
      summary: Get a Currency
      description: |
        Fetch a currency by its ID.
      operationId: getACurrency
      parameters:
        - name: currencyID
          in: path
          description: The ID for the requested currency.
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response.Data'
                  - properties:
                      data:
                        $ref: '#/components/schemas/Response.Currency'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 400
                    title: Bad Request
                    detail: The request was invalid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 401
                    title: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 404
                    title: Currency not found
                    detail: The requested currency could not be found
      deprecated: false
    put:
      tags:
        - Currencies
      summary: Update a Currency
      description: |
        Update a currency.
      operationId: updateACurrency
      parameters:
        - name: currencyID
          in: path
          description: The ID for the requested currency.
          required: true
          style: simple
          schema:
            type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Request.UpdateCurrencies'
                - example:
                    - data:
                        default: true
            examples:
              default:
                value:
                  data:
                    default: true
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response.Data'
                  - properties:
                      data:
                        $ref: '#/components/schemas/Response.Currency'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 400
                    title: Bad Request
                    detail: The request was invalid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 401
                    title: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 404
                    title: Currency not found
                    detail: The requested currency could not be found
      deprecated: false
    delete:
      tags:
        - Currencies
      summary: Delete a Currency
      description: |
        Delete a currency.

        :::caution

        - You can’t delete a default currency.

        :::
      operationId: deleteACurrency
      parameters:
        - name: currencyID
          in: path
          description: The ID for the Currency to delete.
          required: true
          style: simple
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 400
                    title: Bad Request
                    detail: The request was invalid
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.Error'
              example:
                errors:
                  - status: 404
                    title: Currency not found
                    detail: The requested currency could not be found
      deprecated: false
    parameters: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Response.Data:
      type: object
      properties:
        data: {}
    SelfLink:
      type: object
      properties:
        self:
          description: Specifies the URL of this currency.
          type: string
    Timestamps:
      type: object
      properties:
        created_at:
          description: Indicates the creation date of this currency.
          type: string
          example: '2023-11-07T23:04:18.845Z'
        updated_at:
          description: Indicates the updated date of this currency.
          example: '2023-11-07T23:04:18.845Z'
    Response.Meta.Currency:
      type: object
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
        owner:
          description: Indicates whether the owner is store or org.
          example: store
          type: string
    Response.Currency:
      type: object
      properties:
        id:
          description: The unique identifier for this currency.
          example: 0c45e4ec-26e0-4043-86e4-c15b9cf985a0
          type: string
        type:
          description: Represents the type represents the object being returned.
          example: currency
          type: string
        code:
          description: Specifies the currency code. For example, YEN.
          example: GBP
          type: string
        exchange_rate:
          description: Specifies the exchange rate from the default currency.
          example: 1
          type: number
        format:
          description: Specifies how the price currency is displayed. For example, "£{price}".
          example: £{price}
          type: string
        decimal_point:
          description: Indicates the decimal point character.
          example: .
          type: string
        thousand_separator:
          description: Indicates the thousand separator character.
          example: ','
          type: string
        decimal_places:
          description: Indicates how many decimal places the currency is formatted to.
          example: 2
          type: number
        default:
          description: Specifies whether this is the default currency or not. Either `true` or `false`.
          example: true
          type: boolean
        enabled:
          description: Specifies if this currency is available for products. Either `true` or `false`.
          example: true
          type: boolean
        links:
          $ref: '#/components/schemas/SelfLink'
        meta:
          $ref: '#/components/schemas/Response.Meta.Currency'
    Response.Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: An application-specific error code.
                example: '1'
              detail:
                type: string
              status:
                type: integer
                example: 400
              title:
                type: string
    Data.CreateCurrencies:
      required:
        - type
        - code
        - exchange_rate
        - format
        - decimal_point
        - thousand_separator
        - decimal_places
        - default
        - enabled
      type: object
      properties:
        code:
          description: Specifies the currency code. Example YEN.
          type: string
          example: GBP
          maxLength: 3
          minLength: 3
        decimal_places:
          description: Indicates how many decimal places the currency is formatted to.
          type: number
          example: 2
          minimum: 0
        decimal_point:
          description: Indicates the decimal point character.
          type: string
          example: .
        default:
          description: Specifies whether this is the default currency or not. Either `true` or `false`.
          type: boolean
          example: true
        enabled:
          description: Specifies if this currency is available for products. Either `true` or `false`.
          type: boolean
          example: true
        exchange_rate:
          description: Specifies the exchange rate from the default currency.
          type: number
          example: 1
          minimum: 0
        format:
          description: Specifies how the price currency is displayed. For example, "¥{price}".
          type: string
          example: £{price}
        thousand_separator:
          description: Indicates the thousand separator character.
          type: string
          example: ','
        type:
          description: Represents the type represents the object being returned.
          type: string
          example: currency
    Request.CreateCurrencies:
      title: Request.CreateCurrencies
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Data.CreateCurrencies'
    Data.UpdateCurrencies:
      title: Data.UpdateCurrencies
      type: object
      properties:
        default:
          description: Specifies whether this is the default currency or not. Either `true` or `false`.
          type: boolean
          example: true
    Request.UpdateCurrencies:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Data.UpdateCurrencies'