openapi: 3.0.3
info:
  title: Admin Account / Address Store Credits API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Store Credits
paths:
  /api/v2/platform/store_credits:
    get:
      summary: Return a list of Store Credits
      tags:
      - Store Credits
      security:
      - bearer_auth: []
      description: Returns a list of Store Credits
      operationId: store-credits-list
      parameters:
      - name: page
        in: query
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        example: 50
        schema:
          type: integer
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: user,created_by,category,credit_type
        schema:
          type: string
      - name: filter[user_id_eq]
        in: query
        description: ''
        example: '5'
        schema:
          type: string
      - name: filter[created_by_id_eq]
        in: query
        description: ''
        example: '2'
        schema:
          type: string
      - name: filter[amount_gteq]
        in: query
        description: ''
        example: '50.0'
        schema:
          type: string
      - name: filter[currency_eq]
        in: query
        description: ''
        example: USD
        schema:
          type: string
      responses:
        '200':
          description: Records returned
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                    - id: '2'
                      type: store_credit
                      attributes:
                        amount: '150.0'
                        amount_used: '0.0'
                        memo: null
                        deleted_at: null
                        currency: USD
                        amount_authorized: '0.0'
                        originator_type: null
                        created_at: '2022-11-08T19:35:38.714Z'
                        updated_at: '2022-11-08T19:35:38.714Z'
                        public_metadata: {}
                        private_metadata: {}
                        display_amount: $150.00
                        display_amount_used: $0.00
                      relationships:
                        user:
                          data:
                            id: '107'
                            type: user
                        created_by:
                          data:
                            id: '108'
                            type: user
                        store_credit_category:
                          data:
                            id: '14'
                            type: store_credit_category
                        store_credit_type:
                          data:
                            id: '14'
                            type: store_credit_type
                        store_credit_events:
                          data:
                          - id: '3'
                            type: store_credit_event
                    - id: '3'
                      type: store_credit
                      attributes:
                        amount: '150.0'
                        amount_used: '0.0'
                        memo: null
                        deleted_at: null
                        currency: USD
                        amount_authorized: '0.0'
                        originator_type: null
                        created_at: '2022-11-08T19:35:38.722Z'
                        updated_at: '2022-11-08T19:35:38.722Z'
                        public_metadata: {}
                        private_metadata: {}
                        display_amount: $150.00
                        display_amount_used: $0.00
                      relationships:
                        user:
                          data:
                            id: '107'
                            type: user
                        created_by:
                          data:
                            id: '109'
                            type: user
                        store_credit_category:
                          data:
                            id: '15'
                            type: store_credit_category
                        store_credit_type:
                          data:
                            id: '15'
                            type: store_credit_type
                        store_credit_events:
                          data:
                          - id: '4'
                            type: store_credit_event
                    meta:
                      count: 2
                      total_count: 2
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v2/platform/store_credits?page=1&per_page=&include=&filter[user_id_eq]=&filter[created_by_id_eq]=&filter[amount_gteq]=&filter[currency_eq]=
                      next: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      prev: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      last: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      first: http://www.example.com/api/v2/platform/store_credits?filter%5Bamount_gteq%5D=&filter%5Bcreated_by_id_eq%5D=&filter%5Bcurrency_eq%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
              schema:
                $ref: '#/components/schemas/resources_list'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    post:
      summary: Create a Store Credit
      tags:
      - Store Credits
      security:
      - bearer_auth: []
      description: Creates a Store Credit
      operationId: create-store-credit
      parameters:
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: user,created_by,category,credit_type
        schema:
          type: string
      responses:
        '201':
          description: Record created
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '6'
                      type: store_credit
                      attributes:
                        amount: '150.0'
                        amount_used: '0.0'
                        memo: null
                        deleted_at: null
                        currency: USD
                        amount_authorized: '0.0'
                        originator_type: null
                        created_at: '2022-11-08T19:35:39.272Z'
                        updated_at: '2022-11-08T19:35:39.272Z'
                        public_metadata: {}
                        private_metadata: {}
                        display_amount: $150.00
                        display_amount_used: $0.00
                      relationships:
                        user:
                          data:
                            id: '113'
                            type: user
                        created_by:
                          data:
                            id: '114'
                            type: user
                        store_credit_category:
                          data:
                            id: '18'
                            type: store_credit_category
                        store_credit_type:
                          data:
                            id: '18'
                            type: store_credit_type
                        store_credit_events:
                          data:
                          - id: '7'
                            type: store_credit_event
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: User can't be blank, Category can't be blank, Created by can't be blank, Currency can't be blank, Amount must be greater than 0, Amount used Cannot be greater than amount., and Amount authorized Exceeds total credits.
                    errors:
                      user:
                      - can't be blank
                      category:
                      - can't be blank
                      created_by:
                      - can't be blank
                      currency:
                      - can't be blank
                      amount:
                      - must be greater than 0
                      amount_used:
                      - Cannot be greater than amount.
                      amount_authorized:
                      - Exceeds total credits.
              schema:
                $ref: '#/components/schemas/validation_errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_store_credit_params'
  /api/v2/platform/store_credits/{id}:
    get:
      summary: Return a Store Credit
      tags:
      - Store Credits
      security:
      - bearer_auth: []
      description: Returns a Store Credit
      operationId: show-store-credit
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: user,created_by,category,credit_type
        schema:
          type: string
      responses:
        '200':
          description: Record found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '7'
                      type: store_credit
                      attributes:
                        amount: '150.0'
                        amount_used: '0.0'
                        memo: null
                        deleted_at: null
                        currency: USD
                        amount_authorized: '0.0'
                        originator_type: null
                        created_at: '2022-11-08T19:35:39.554Z'
                        updated_at: '2022-11-08T19:35:39.554Z'
                        public_metadata: {}
                        private_metadata: {}
                        display_amount: $150.00
                        display_amount_used: $0.00
                      relationships:
                        user:
                          data:
                            id: '115'
                            type: user
                        created_by:
                          data:
                            id: '116'
                            type: user
                        store_credit_category:
                          data:
                            id: '19'
                            type: store_credit_category
                        store_credit_type:
                          data:
                            id: '20'
                            type: store_credit_type
                        store_credit_events:
                          data:
                          - id: '8'
                            type: store_credit_event
              schema:
                $ref: '#/components/schemas/resource'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    patch:
      summary: Update a Store Credit
      tags:
      - Store Credits
      security:
      - bearer_auth: []
      description: Updates a Store Credit
      operationId: update-store-credit
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: user,created_by,category,credit_type
        schema:
          type: string
      responses:
        '200':
          description: Record updated
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '9'
                      type: store_credit
                      attributes:
                        amount: '500.0'
                        amount_used: '0.0'
                        memo: The user is awarded
                        deleted_at: null
                        currency: CAD
                        amount_authorized: '0.0'
                        originator_type: null
                        created_at: '2022-11-08T19:35:40.170Z'
                        updated_at: '2022-11-08T19:35:40.405Z'
                        public_metadata:
                          loyalty_reward: true
                        private_metadata: {}
                        display_amount: $500.00
                        display_amount_used: $0.00
                      relationships:
                        user:
                          data:
                            id: '119'
                            type: user
                        created_by:
                          data:
                            id: '120'
                            type: user
                        store_credit_category:
                          data:
                            id: '21'
                            type: store_credit_category
                        store_credit_type:
                          data:
                            id: '22'
                            type: store_credit_type
                        store_credit_events:
                          data:
                          - id: '10'
                            type: store_credit_event
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: Amount must be greater than 0, Amount used Cannot be greater than amount., and Amount authorized Exceeds total credits.
                    errors:
                      amount:
                      - must be greater than 0
                      amount_used:
                      - Cannot be greater than amount.
                      amount_authorized:
                      - Exceeds total credits.
              schema:
                $ref: '#/components/schemas/validation_errors'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_store_credit_params'
    delete:
      summary: Delete a Store Credit
      tags:
      - Store Credits
      security:
      - bearer_auth: []
      description: Deletes a Store Credit
      operationId: delete-store-credit
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Record deleted
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    resource_properties:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
      required:
      - id
      - type
      - attributes
      x-internal: false
    update_store_credit_params:
      type: object
      properties:
        store_credit:
          type: object
          required:
          - user_id
          - category_id
          - type_id
          - created_by_id
          - currency
          - store_id
          - amount
          properties:
            user_id:
              type: string
              example: '2'
            category_id:
              type: string
              example: '4'
            created_by_id:
              type: string
              example: '5'
            amount:
              type: number
              example: 25.0
            amount_used:
              type: number
              example: 10.0
            memo:
              type: string
              example: This credit was given as a refund
            currency:
              type: string
              example: USD
            amount_authorized:
              type: number
              example: 15.5
            originator_id:
              type: string
              example: '3'
            originator_type:
              type: string
              example: Refund
            type_id:
              type: string
              example: '1'
            store_id:
              type: string
              example: '2'
            public_metadata:
              type: object
            private_metadata:
              type: object
      required:
      - store_credit
      x-internal: false
    error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
      x-internal: false
    resources_list:
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/resource_properties'
        meta:
          type: object
          properties:
            count:
              type: integer
            total_count:
              type: integer
            total_pages:
              type: integer
          required:
          - count
          - total_count
          - total_pages
        links:
          type: object
          properties:
            self:
              type: string
            next:
              type: string
            prev:
              type: string
            last:
              type: string
            first:
              type: string
          required:
          - self
          - next
          - prev
          - last
          - first
      required:
      - data
      - meta
      - links
      x-internal: false
    resource:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/resource_properties'
      required:
      - data
      x-internal: false
    create_store_credit_params:
      type: object
      properties:
        store_credit:
          type: object
          required:
          - user_id
          - category_id
          - type_id
          - created_by_id
          - currency
          - store_id
          - amount
          properties:
            user_id:
              type: string
              example: '2'
            category_id:
              type: string
              example: '4'
            created_by_id:
              type: string
              example: '5'
            amount:
              type: number
              example: 25.0
            amount_used:
              type: number
              example: 10.0
            memo:
              type: string
              example: This credit was given as a refund
            currency:
              type: string
              example: USD
            amount_authorized:
              type: number
              example: 15.5
            originator_id:
              type: string
              example: '3'
            originator_type:
              type: string
              example: Refund
            type_id:
              type: string
              example: '1'
            store_id:
              type: string
              example: '2'
            public_metadata:
              type: object
            private_metadata:
              type: object
      required:
      - store_credit
      x-internal: false
    validation_errors:
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
      required:
      - error
      - errors
      x-internal: false
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Products & Catalog
  tags:
  - Products
  - Variants
  - Option Types
  - Custom Fields
  - Channels
- name: Pricing
  tags:
  - Pricing
  - Markets
- name: Orders & Fulfillment
  tags:
  - Orders
  - Payments
  - Fulfillments
  - Refunds
- name: Customers
  tags:
  - Customers
  - Customer Groups
- name: Promotions & Gift Cards
  tags:
  - Promotions
  - Gift Cards
- name: Data
  tags:
  - Exports
- name: Configuration
  tags:
  - Settings
  - Stock Locations
  - Payment Methods
  - Staff
  - API Keys
  - Allowed Origins
  - Webhooks