openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26T19:10:23Z
  title: Addresses Introduction
  description: |
    The Addresses API allows you to organize customer addresses. Addresses are a sub-resource of a `customer`, a customer can have multiple addresses, such as home, work, and neighbour.

    You can use a customer address with an [implicit access token](/docs/api/authentication/create-an-access-token), which is recommended for client-side interactions. You can also use a [client_credentials access token](/docs/api/authentication/create-an-access-token), which is recommended for back-end interactions.
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
  - url: https://useast.api.elasticpath.com
    description: US East
  - url: https://euwest.api.elasticpath.com
    description: EU West
security:
  - BearerToken: []
tags:
  - name: Customer Addresses
    description: The API to organize customer addresses.
paths:
  /v2/customers/{customerID}/addresses:
    post:
      tags:
        - Customer Addresses
      summary: Create a Customer Address
      description: Create an address for a Customer.
      operationId: post-v2-customer-address
      parameters:
        - name: customerID
          in: path
          description: The ID of the customer you want to create an address for.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    $ref: '#/components/schemas/CustomerAddressResponse'
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    $ref: '#/components/schemas/CustomerAddressResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
    get:
      tags:
        - Customer Addresses
      summary: Get Customer Addresses
      description: |
        Get all addresses for a Customer.

        You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

        ### Filtering

        The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) addresses:

        | Attribute      | Operators                       | Example                               |
        |----------------|---------------------------------|---------------------------------------|
        | `name`         | `eq`,`in`,`like`,`ilike`,`text` | `ilike(name,"*home*")`                |
        | `first_name`   | `eq`,`in`,`like`,`ilike`,`text` | `ilike(first_name,"Ron*")`            |
        | `last_name`    | `eq`,`in`,`like`,`ilike`,`text` | `ilike(last_name,"*swan*")`           |
        | `phone_number` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(phone_number,"*555*")`         |
        | `company_name` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(company_name,"*enterprises*")` |
        | `instructions` | `eq`,`in`,`like`,`ilike`,`text` | `text(instructions,"behind bin")`     |
        | `line_1`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_1,"*Sunny Street*")`      |
        | `line_2`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_2,"*Unit*")`              |
        | `city`         | `eq`,`in`,`like`,`ilike`,`text` | `eq(city,"Sunny Town")`               |
        | `county`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(county,"Sunnyville")`             |
        | `region`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(region,"California")`             |
        | `postcode`     | `eq`,`in`,`like`,`ilike`,`text` | `eq(postcode,"SU33 1YY")`             |
        | `country`      | `eq`,`in`,`like`,`ilike`,`text` | `eq(country,"GB")`                    |
      operationId: get-v2-customer-addresses
      parameters:
        - name: customerID
          in: path
          description: The ID of the customer you want to retrieve.
          required: true
          schema:
            type: string
        - name: page[offset]
          in: query
          description: The number of records to offset the results by.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
        - name: page[limit]
          in: query
          description: The number of records per page. If not specified, defaults to the `page_length` setting from the Settings API.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: page[total_method]
          in: query
          description: The method used to calculate the total count. `lower_bound` limits expensive count operations, `observed` uses a lightweight +1 fetch strategy that will indicate if there is a next page.
          required: false
          schema:
            type: string
            enum:
              - lower_bound
              - observed
            default: lower_bound
        - name: filter
          in: query
          description: Filter addresses using a simple query language.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerAddressResponse'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
      security:
        - BearerToken: []
  /v2/customers/{customerID}/addresses/{addressID}:
    get:
      tags:
        - Customer Addresses
      summary: Get an Customer Address
      description: Get an address for a Customer.
      operationId: get-v2-customer-address
      parameters:
        - name: customerID
          in: path
          description: The ID of the customer you want to retrieve.
          required: true
          schema:
            type: string
        - name: addressID
          in: path
          description: The ID of the address you want to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    $ref: '#/components/schemas/CustomerAddressResponse'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
      security:
        - BearerToken: []
    put:
      tags:
        - Customer Addresses
      summary: Update an Customer Address
      description: Update an address for a Customer.
      operationId: put-v2-customer-address
      parameters:
        - name: customerID
          in: path
          description: The ID of the customer you want to create an address for.
          required: true
          schema:
            type: string
        - name: addressID
          in: path
          description: The ID of the customer you want to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    $ref: '#/components/schemas/CustomerAddressResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
      security:
        - BearerToken: []
    delete:
      tags:
        - Customer Addresses
      summary: Delete a Customer Address
      description: Delete an address for a Customer.
      operationId: delete-v2-customer-address
      parameters:
        - name: customerID
          in: path
          description: The ID of the customer that contains the address to delete.
          required: true
          schema:
            type: string
        - name: addressID
          in: path
          description: The ID of the address to delete.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '404':
          $ref: '#/components/responses/ErrorNotFound'
      security:
        - BearerToken: []
components:
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
  schemas:
    MetaTimestamps:
      type: object
      properties:
        timestamps:
          type: object
          properties:
            created_at:
              description: The date the address is created.
              type: string
              example: '2021-02-23T09:40:33.882Z'
            updated_at:
              description: The date the address is updated.
              type: string
              example: '2021-02-23T09:40:33.882Z'
    PaginationPage:
      type: object
      properties:
        limit:
          type: integer
          description: The maximum number of records per page.
          example: 25
        offset:
          type: integer
          description: The current offset by number of records.
          example: 0
        current:
          type: integer
          description: The current page number.
          example: 1
        total:
          type: integer
          description: The total number of pages.
          example: 3
    PaginationResults:
      type: object
      properties:
        total:
          type: integer
          description: The total number of results.
          example: 75
        total_method:
          type: string
          description: The method used to calculate the total. `exact` means the precise count is known, `lower_bound` means the count is at least this value, `observed` means the count is estimated from observations.
          enum:
            - exact
            - lower_bound
            - observed
          example: exact
    PaginationMeta:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PaginationPage'
        results:
          $ref: '#/components/schemas/PaginationResults'
    PaginationLinks:
      type: object
      properties:
        current:
          type: string
          description: The URL to the current page.
          example: https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25
        first:
          type: string
          description: The URL to the first page.
          example: https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25
        last:
          type:
            - string
            - 'null'
          description: The URL to the last page. May be null if the total is unknown.
          example: https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=50&page[limit]=25
        next:
          type:
            - string
            - 'null'
          description: The URL to the next page. Null if on the last page.
          example: https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=25&page[limit]=25
        prev:
          type:
            - string
            - 'null'
          description: The URL to the previous page. Null if on the first page.
          example: null
    Address:
      type: object
      properties:
        type:
          type: string
          description: Specifies the the type of object. Set this value to `address`.
          default: address
        first_name:
          type: string
          description: The first name of the recipient on this address.
          example: Ron
        last_name:
          type: string
          description: The last name of the recipient on this address.
          example: Swanson
        name:
          type: string
          description: The name for the address saved, such as `home`, `work` or `wife’s office`.
          example: Home
        phone_number:
          type: string
          description: A phone number for this address.
          example: (555) 555-1234
        instructions:
          type: string
          description: Any delivery instructions for this address.
          example: Leave behind bin
        company_name:
          type: string
          description: The company name at this address.
          example: Ron Swanson Enterprises
        line_1:
          type: string
          description: The first portion of the address, usually the street address.
          example: 1 Sunny Street
        line_2:
          type: string
          description: The second portion of the address, usually an apartment or unit number.
          example: Unit 101
        city:
          type: string
          description: The city for this address.
          example: Sunny Town
        county:
          type: string
          description: The county for this address.
          example: Sunnyville
        region:
          type: string
          description: The state, province, territory, etc. for this address.
          example: acc-legal-name
        postcode:
          type: string
          description: The ZIP Code, Postcode, or other postal reference string for this delivery address.
          example: SU33 1YY
        country:
          type: string
          description: A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.
          example: GB
    AddressResponse:
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            id:
              type: string
              description: The unique identifier for an Address.
              example: 5f8da740-6680-463e-b31c-190b2db4bf9d
            meta:
              $ref: '#/components/schemas/MetaTimestamps'
            links:
              type: object
              properties:
                self:
                  description: A URL to the specific resource.
                  type: string
                  example: https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses
    CustomerAddressResponse:
      allOf:
        - $ref: '#/components/schemas/AddressResponse'
        - type: object
          properties:
            relationships:
              type: object
              properties:
                customer:
                  type: object
                  properties:
                    id:
                      description: The ID of the customer.
                      type: string
                      example: 11afcf9b-971b-4fdb-8e10-f2ecf970718e
                    type:
                      description: The type of object being returned.
                      type: string
                      example: customer
    Error:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP response code of the error.
        title:
          type: string
          description: A brief summary of the error.
        detail:
          type: string
          description: Optional additional detail about the error.
        source:
          type: string
          description: Optional field indicating the source of the error.
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  responses:
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad-request-error:
              value:
                errors:
                  - status: 400
                    title: Bad Request
                    detail: 'Validation failed: field ''Name'' on the ''min'' tag.'
    ErrorNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found-error:
              value:
                errors:
                  - status: 404
                    title: Not Found
                    detail: customer not found