openapi: 3.0.3
info:
  title: Admin Account / Address Addresses 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: Addresses
paths:
  /api/v2/platform/addresses:
    get:
      summary: Return a list of Addresses
      tags:
      - Addresses
      security:
      - bearer_auth: []
      description: Returns a list of Addresses
      operationId: addresses-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,country,state
        schema:
          type: string
      - name: filter[user_id_eq]
        in: query
        description: ''
        example: '1'
        schema:
          type: string
      - name: filter[firstname_cont]
        in: query
        description: ''
        example: John
        schema:
          type: string
      responses:
        '200':
          description: Records returned
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                    - id: '1'
                      type: address
                      attributes:
                        firstname: John
                        lastname: Doe
                        address1: 1 Lovely Street
                        address2: Northwest
                        city: Herndon
                        zipcode: '35005'
                        phone: 555-555-0199
                        state_name: null
                        alternative_phone: 555-555-0199
                        company: Company
                        created_at: '2022-11-08T19:33:50.821Z'
                        updated_at: '2022-11-08T19:33:50.821Z'
                        deleted_at: null
                        label: null
                        public_metadata: {}
                        private_metadata: {}
                      relationships:
                        country:
                          data:
                            id: '1'
                            type: country
                        state:
                          data:
                            id: '1'
                            type: state
                        user:
                          data: null
                    - id: '2'
                      type: address
                      attributes:
                        firstname: John
                        lastname: Doe
                        address1: 2 Lovely Street
                        address2: Northwest
                        city: Herndon
                        zipcode: '35005'
                        phone: 555-555-0199
                        state_name: null
                        alternative_phone: 555-555-0199
                        company: Company
                        created_at: '2022-11-08T19:33:50.825Z'
                        updated_at: '2022-11-08T19:33:50.825Z'
                        deleted_at: null
                        label: null
                        public_metadata: {}
                        private_metadata: {}
                      relationships:
                        country:
                          data:
                            id: '1'
                            type: country
                        state:
                          data:
                            id: '2'
                            type: state
                        user:
                          data: null
                    meta:
                      count: 2
                      total_count: 2
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v2/platform/addresses?page=1&per_page=&include=&filter[user_id_eq]=&filter[firstname_cont]=
                      next: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      prev: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      last: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%5D=&filter%5Buser_id_eq%5D=&include=&page=1&per_page=
                      first: http://www.example.com/api/v2/platform/addresses?filter%5Bfirstname_cont%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 an Address
      tags:
      - Addresses
      security:
      - bearer_auth: []
      description: Creates an Address
      operationId: create-address
      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,country,state
        schema:
          type: string
      responses:
        '201':
          description: Record created
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '5'
                      type: address
                      attributes:
                        firstname: John
                        lastname: Doe
                        address1: 5 Lovely Street
                        address2: Northwest
                        city: Herndon
                        zipcode: '35005'
                        phone: 555-555-0199
                        state_name: null
                        alternative_phone: 555-555-0199
                        company: Company
                        created_at: '2022-11-08T19:33:51.471Z'
                        updated_at: '2022-11-08T19:33:51.471Z'
                        deleted_at: null
                        label: null
                        public_metadata: {}
                        private_metadata: {}
                      relationships:
                        country:
                          data:
                            id: '4'
                            type: country
                        state:
                          data:
                            id: '5'
                            type: state
                        user:
                          data:
                            id: '1'
                            type: user
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: First Name can't be blank, Last Name can't be blank, Address can't be blank, City can't be blank, Country can't be blank, Zip Code can't be blank, and Phone can't be blank
                    errors:
                      firstname:
                      - can't be blank
                      lastname:
                      - can't be blank
                      address1:
                      - can't be blank
                      city:
                      - can't be blank
                      country:
                      - can't be blank
                      zipcode:
                      - can't be blank
                      phone:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/validation_errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_address_params'
  /api/v2/platform/addresses/{id}:
    get:
      summary: Return an Address
      tags:
      - Addresses
      security:
      - bearer_auth: []
      description: Returns an Address
      operationId: show-address
      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,country,state
        schema:
          type: string
      responses:
        '200':
          description: Record found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '6'
                      type: address
                      attributes:
                        firstname: John
                        lastname: Doe
                        address1: 6 Lovely Street
                        address2: Northwest
                        city: Herndon
                        zipcode: '35005'
                        phone: 555-555-0199
                        state_name: null
                        alternative_phone: 555-555-0199
                        company: Company
                        created_at: '2022-11-08T19:33:51.740Z'
                        updated_at: '2022-11-08T19:33:51.740Z'
                        deleted_at: null
                        label: null
                        public_metadata: {}
                        private_metadata: {}
                      relationships:
                        country:
                          data:
                            id: '6'
                            type: country
                        state:
                          data:
                            id: '6'
                            type: state
                        user:
                          data: null
              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 an Address
      tags:
      - Addresses
      security:
      - bearer_auth: []
      description: Updates an Address
      operationId: update-address
      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,country,state
        schema:
          type: string
      responses:
        '200':
          description: Record updated
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '8'
                      type: address
                      attributes:
                        firstname: Jack
                        lastname: Doe
                        address1: 8 Lovely Street
                        address2: Northwest
                        city: Herndon
                        zipcode: '35005'
                        phone: 555-555-0199
                        state_name: null
                        alternative_phone: 555-555-0199
                        company: Company
                        created_at: '2022-11-08T19:33:52.269Z'
                        updated_at: '2022-11-08T19:33:52.501Z'
                        deleted_at: null
                        label: null
                        public_metadata: {}
                        private_metadata: {}
                      relationships:
                        country:
                          data:
                            id: '9'
                            type: country
                        state:
                          data:
                            id: '8'
                            type: state
                        user:
                          data: null
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: First Name can't be blank and Last Name can't be blank
                    errors:
                      firstname:
                      - can't be blank
                      lastname:
                      - can't be blank
              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_address_params'
    delete:
      summary: Delete an Address
      tags:
      - Addresses
      security:
      - bearer_auth: []
      description: Deletes an Address
      operationId: delete-address
      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
    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
    validation_errors:
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
      required:
      - error
      - errors
      x-internal: false
    create_address_params:
      type: object
      properties:
        address:
          type: object
          required:
          - country_id
          - address1
          - city
          - zipcode
          - phone
          - firstname
          - lastname
          properties:
            country_id:
              type: string
              example: '224'
            state_id:
              type: string
              example: '516'
            state_name:
              type: string
              example: New York
            address1:
              type: string
              example: 5th ave
            address2:
              type: string
              example: 1st suite
            city:
              type: string
              example: NY
            zipcode:
              type: string
              example: '10001'
            phone:
              type: string
              example: +1 123 456 789
            alternative_phone:
              type: string
            firstname:
              type: string
              example: John
            lastname:
              type: string
              example: Snow
            label:
              type: string
              example: My home address
            company:
              type: string
              example: Vendo Connect Inc
            user_id:
              type: string
            public_metadata:
              type: object
              example:
                distance_from_nearest_city_in_km: 10
                location_type: building
            private_metadata:
              type: object
              example:
                close_to_shop: true
      required:
      - address
      x-internal: false
    resource:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/resource_properties'
      required:
      - data
      x-internal: false
    update_address_params:
      type: object
      properties:
        address:
          type: object
          properties:
            country_id:
              type: string
              example: '224'
            state_id:
              type: string
              example: '516'
            state_name:
              type: string
              example: New York
            address1:
              type: string
              example: 5th ave
            address2:
              type: string
              example: 1st suite
            city:
              type: string
              example: NY
            zipcode:
              type: string
              example: '10001'
            phone:
              type: string
              example: +1 123 456 789
            alternative_phone:
              type: string
            firstname:
              type: string
              example: John
            lastname:
              type: string
              example: Snow
            label:
              type: string
              example: My home address
            company:
              type: string
              example: Vendo Connect Inc
            user_id:
              type: string
            public_metadata:
              type: object
              example:
                distance_from_city_in_km: 10
                location_type: building
            private_metadata:
              type: object
              example:
                close_to_shop: true
      required:
      - address
      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