The `Account Membership` resource represents the relationship between an account and an account member. This relationship is many to many. Each account can have multiple account members, and each account member can be a member of multiple accounts.
openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Account Membership API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
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: Account Membership
description: The `Account Membership` resource represents the relationship between an account and an account member. This relationship is many to many. Each account can have multiple account members, and each account member can be a member of multiple accounts.
externalDocs:
url: https://elasticpath.dev/docs/commerce-cloud/accounts/using-account-membership-api/overview
paths:
/v2/accounts/{accountID}/account-memberships:
post:
tags:
- Account Membership
summary: Create an Account Membership
description: ':::caution
You can only create up to 1000 account memberships in an account.
:::
'
operationId: post-v2-accounts-accountID-account-memberships
parameters:
- name: accountID
in: path
description: The unique identifier of the account that the account is associated with.
required: true
schema:
type: string
format: uuid
requestBody:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccountMembership'
examples:
Create account membership:
value:
data:
type: account_membership
account_member_id: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccountMembershipResponse'
links:
type: object
properties:
self:
description: A URL to the specific resource.
type: string
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'500':
$ref: '#/components/responses/InternalServerError'
get:
tags:
- Account Membership
summary: Get all Account Memberships
description: 'You can also use `include=account_member` to retrieve details about the account members associated with the account memberships. With this option, you can get more information about the account members such as name and email in a single request. For more information see [including resources](/guides/Getting-Started/includes).
### Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) account memberships.
| Operator | Description |
| :--- | :--- |
| `eq` | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like` | Checks if the operand contains the specified string. You can use wildcard characters in operand. |
| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,00000000-0000-1000-8000-0000000)` |'
operationId: get-v2-accounts-accountID-account-memberships
parameters:
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/page-limit'
- $ref: '#/components/parameters/page-offset'
- $ref: '#/components/parameters/include-account-member'
- name: accountID
in: path
description: The ID of the account for which you want to get the list of unassigned account members.
required: true
schema:
type: string
format: uuid
- name: sort
in: query
description: Specifies the order in which account memberships will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).
required: false
schema:
type: string
enum:
- created_at
- -created_at
- updated_at
- -updated_at
- id
- -id
x-enumDescriptions:
created_at: Sort in increasing order of creation
-created_at: Sort in decreasing order of creation
id: Sort in increasing order of ID
-id: Sort in decreasing order of ID
updated_at: Sort in increasing order of last update
-updated_at: Sort in decreasing order of last update
example: id
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/AccountMembershipResponse'
- type: object
properties:
account_member_id:
$ref: '#/components/schemas/UUID'
description: The unique identifier for an Account Member.
meta:
$ref: '#/components/schemas/MetaList'
links:
type: object
properties:
current:
description: Always the current page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
first:
description: Always the first page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
last:
description: Always `null` if there is only one page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
next:
description: Always `null` if there is only one page.
type: string
example: null
prev:
description: Always `null` if the user is on the first page.
type: string
example: null
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/account-members/{accountMemberId}/account-memberships:
get:
tags:
- Account Membership
summary: Get a List of Account Memberships of Account Member
description: 'You can also use `include=account` to retrieve details about the accounts associated with the account memberships. For more information see [including resources](/guides/Getting-Started/includes).
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) account memberships.
| Operator | Description |
| :--- | :--- |
| `eq` | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like` | Checks if the operand contains the specified string. You can use wildcard characters in operand. |
| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,00000000-0000-1000-8000-0000000)` |
'
operationId: get-v2-account-members-accountMemberId-account-memberships
parameters:
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/include-account'
- name: accountMemberId
in: path
description: The ID of the account member for which you want to list the memberships.
required: true
schema:
type: string
format: uuid
- name: sort
in: query
description: Specifies the order in which account memberships will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).
required: false
schema:
type:
- string
enum:
- created_at
- -created_at
- id
- -id
- updated_at
- -updated_at
x-enumDescriptions:
created_at: Sort in increasing order of creation
-created_at: Sort in decreasing order of creation
id: Sort in increasing order of ID
-id: Sort in decreasing order of ID
updated_at: Sort in increasing order of last update
-updated_at: Sort in decreasing order of last update
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/AccountMembershipResponseUsingAccountMemberId'
- type: object
properties:
account_member_id:
$ref: '#/components/schemas/UUID'
description: The unique identifier for an Account Member.
meta:
$ref: '#/components/schemas/MetaList'
links:
type: object
properties:
current:
description: Always the current page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
first:
description: Always the first page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
last:
description: Always `null` if there is only one page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25
next:
description: Always `null` if there is only one page.
type: string
example: null
prev:
description: Always `null` if the user is on the first page.
type: string
example: null
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/accounts/{accountID}/account-memberships/unassigned-account-members:
get:
tags:
- Account Membership
summary: Get a List of Unassigned Account Members
description: 'Use this resource to get a list of all account members that are not assigned to an account.
### Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) unassigned account members.
| Operator | Description |
| :------- | :--------------------------------------------------------------------------------------------------- |
| `eq` | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like` | Checks if the operand contains the specified string. You can use wildcard characters in operand. |
| Attribute | Type | Operator | Example |
| :-------- | :------- | :------------ | :--------------------------------- |
| `email` | `string` | `eq` / `like` | `eq(email,ronswanson@example.com)` |
| `name` | `string` | `eq` / `like` | `like(name,*swan*)` |
:::note
You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).
:::'
operationId: get-v2-accounts-accountID-account-memberships-unassigned-account-members
parameters:
- $ref: '#/components/parameters/page-limit'
- $ref: '#/components/parameters/page-offset'
- $ref: '#/components/parameters/filter'
- name: accountID
in: path
description: The ID of the account for which you want to get the list of unassigned account members.
required: true
schema:
type: string
format: uuid
- name: sort
in: query
description: Specifies the order in which unassigned account members will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).
required: false
schema:
type: string
enum:
- created_at
- -created_at
- updated_at
- updated_at
x-enumDescriptions:
created_at: Sort in increasing order of creation
-created_at: Sort in decreasing order of creation
updated_at: Sort in increasing order of last update
-updated_at: Sort in decreasing order of last update
example: id
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AccountMemberResponse'
meta:
$ref: '#/components/schemas/MetaList'
links:
type: object
properties:
current:
description: Always the current page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25
first:
description: Always the first page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25
last:
description: Always `null` if there is only one page.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25
next:
description: Always `null` if there is only one page.
type: string
example: null
prev:
description: Always `null` if the user is on the first page.
type: string
example: null
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/accounts/{accountID}/account-memberships/{membershipID}:
get:
tags:
- Account Membership
summary: Get an Account Membership
description: 'Get an account membership from an account in your store.
You can also use `include=account_member` to retrieve details about the account member associated with this account membership. With this option, you can get more information about the account member such as name and email in a single request. For more information see [including resources](/guides/Getting-Started/includes).
'
operationId: get-v2-accounts-accountID-account-memberships-membershipID
parameters:
- $ref: '#/components/parameters/include-account-member'
- name: accountID
in: path
description: The unique identifier of the account that the account member is associated with.
required: true
schema:
type: string
format: uuid
- name: membershipID
in: path
description: The unique identifier of the account membership to update the details of the account member.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccountMembershipResponse'
links:
type: object
properties:
self:
description: A URL to the specific resource.
type: string
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
put:
tags:
- Account Membership
summary: Update an Account Membership
description: You can update and extend an account member details using [core flows](/docs/api/flows/flows#extend-an-existing-resource). However, you cannot update the `account_member_id` of an account member.
operationId: put-v2-accounts-accountID-account-memberships-membershipID
parameters:
- name: accountID
in: path
description: The unique identifier of the account that the account member is associated with.
required: true
schema:
type: string
format: uuid
- name: membershipID
in: path
description: The unique identifier of the account membership to update the details of the account member.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccountMembership'
required:
- type
- account_member_id
examples:
Update account membership:
value:
data:
type: account_membership
account_member_id: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AccountMembershipResponse'
links:
type: object
properties:
self:
description: A URL to the specific resource.
type: string
example: https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
tags:
- Account Membership
summary: Delete an Account Membership
description: Delete a membership from an account
operationId: delete-v2-accounts-accountID-account-memberships-membershipID
parameters:
- name: accountID
in: path
description: The unique identifier of the account that the account member is associated with.
required: true
schema:
type: string
format: uuid
- name: membershipID
in: path
description: The unique identifier of the account membership to update the details of the account member.
required: true
schema:
type: string
format: uuid
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
AccountMember:
type: object
properties:
id:
description: The unique identifier for the account member.
type: string
format: uuid
example: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
type:
description: The type of the object that is returned.
type: string
const: account_member
name:
description: The name of the account member.
type: string
example: Ron Swanson
given_name:
description: The given name of the account member. This field is optional and not computed or extracted from the name field.
type:
- string
- 'null'
example: Ron
middle_name:
description: The middle name of the account member. This field is optional and not computed or extracted from the name field.
type:
- string
- 'null'
example: Ulysses
family_name:
description: The family name of the account member. This field is optional and not computed or extracted from the name field.
type:
- string
- 'null'
example: Swanson
email:
description: The email address of the account member.
type: string
format: email
example: ron@swanson.com
AccountMembershipResponseUsingAccountMemberId:
type: object
properties:
id:
description: Represents the unique identifier for the account membership.
type: string
format: uuid
example: 24e939f6-178f-497b-9d64-5bf2b5a70a2e
type:
description: Represents the type of the object returned.
type: string
const: account_membership
meta:
$ref: '#/components/schemas/MetaTimestamps'
relationships:
type: object
properties:
account:
type: object
properties:
data:
type: object
properties:
id:
description: Specifies the ID of the account.
type: string
format: uuid
example: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
type:
description: Specifies the type of the Account.
type: string
const: account
links:
type: object
properties:
self:
description: A URL to the specific resource.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e
Error:
type: object
required:
- status
- title
properties:
title:
type: string
description: A brief summary of the error.
examples:
- Bad Request
status:
type: string
format: string
description: The HTTP response code of the error.
examples:
- '400'
detail:
type: string
description: Optional additional detail about the error.
examples:
- The field 'name' is required
MetaListPage:
type: object
properties:
limit:
type: integer
description: The maximum number of records per page for this response. You can set this value up to 100.
example: 25
current:
type: integer
description: The current page.
example: 0
offset:
type: integer
description: The current offset by number of records, not pages. Offset is zero-based.
example: 0
total:
type: integer
description: The total page count.
example: 1
ErrorResponse:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
MetaTimestamps:
type: object
properties:
timestamps:
type: object
properties:
created_at:
description: The date the resource is created.
type: string
example: '2021-02-23T09:40:33.882Z'
updated_at:
description: The date the resource is updated.
type: string
example: '2021-02-23T09:40:33.882Z'
MetaList:
type: object
properties:
page:
$ref: '#/components/schemas/MetaListPage'
results:
$ref: '#/components/schemas/MetaListResults'
UUID:
type: string
description: The unique identifier.
format: uuid
x-go-type: uuid.UUID
x-go-type-import:
name: uuid
path: github.com/google/uuid
example: deb6b25f-8451-4211-9a22-95610333df23
AccountMembershipResponse:
type: object
properties:
id:
description: Represents the unique identifier for the account membership.
type: string
format: uuid
example: 24e939f6-178f-497b-9d64-5bf2b5a70a2e
type:
description: Represents the type of the object returned.
type: string
const: account_membership
meta:
$ref: '#/components/schemas/MetaTimestamps'
relationships:
type: object
properties:
account_member:
type: object
properties:
data:
type: object
properties:
id:
description: Specifies the ID of the account member.
type: string
format: uuid
example: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
type:
description: Specifies the type of the account member.
type: string
const: account_member
links:
type: object
properties:
self:
description: A URL to the specific resource.
type: string
format: uri
example: https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e
MetaListResults:
type: object
properties:
total:
type: integer
description: The total number of results after applying filters, if any, or all results.
example: 1
AccountMemberResponse:
allOf:
- $ref: '#/components/schemas/AccountMember'
- type: object
properties:
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/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953
AccountMembership:
type: object
properties:
account_member_id:
type: string
format: uuid
description: Specifies the unique identifier of the account member that the membership is associated with.
example: 908f7849-60da-4e4a-a3b1-51d4cbe3b953
type:
type: string
const: account_membership
description: Specifies the type of the object. Set this value to `account_membership`.
responses:
NotFoundError:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
not-found-error:
value:
errors:
- title: Not Found
status: '404'
detail: account not found
ConflictError:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
conflict-error:
value:
errors:
- title: Conflict
status: '409'
detail: account membership with the given account id and account member id already exists
UnprocessableEntity:
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unprocessable-entity:
value:
errors:
- title: Unprocessable Entity
status: '422'
detail: store id mismatch
InternalServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
errors:
- title: Internal Server Error
status: '500'
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-account-membership-api-openapi.yml