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 Custom APIs 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: Custom APIs
description: 'Custom APIs allow you to extend the capabilities of Commerce. With Custom APIs, you can efficiently manage large data sets while benefiting from both simple and complex multidimensional filtering options. Combining Custom APIs with [Composer](/docs/composer/index) enables you to deploy custom behaviors and integrations, allowing you to implement capabilities unique to your business without having to build and host that functionality from scratch.
A Custom API is composed of one or more [Custom Fields](/docs/api/commerce-extensions/custom-fields) and allows you to create [Entries](/docs/api/commerce-extensions/custom-api-entries). In database terms, a Custom API can be thought of as a table, with fields representing the columns of the table, and entries serving as the database records.
## Custom APIs vs Non-Core Flows
Custom APIs are the next generation of Non-Core Flows. Here is a comparison of current features of Non-Core Flows and Custom APIs. This will be updated as we release more capabilities.
| Feature | Non-Core Flows | Commerce Extensions |
|---------------------------------------------------------------------------------------------------------------------------|----------------|----------------------------------------------------------------|
| Build new APIs | ✅ | ✅ |
| Access Level | Implicit | [Customizable](/docs/api/permissions/custom-api-role-policies) |
| [Filtering](/docs/api/commerce-extensions/list-custom-api-entries#filtering) | ⛔️ | ✅ |
| [Sorting](/docs/api/commerce-extensions/list-custom-api-entries#sorting) | ⛔️ | ✅ |
| [Events](/docs/api/commerce-extensions/custom-api-entries#events) | ⛔️ | ✅ |
| [Conditional Updates](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#conditional-updates) | ⛔️ | ✅ |
The [Custom Fields Overview](/docs/api/commerce-extensions/custom-fields) lists the comparison of different types and validation available in Custom APIs vs Non-Core Flows.
'
paths:
/v2/settings/extensions/custom-apis:
post:
tags:
- Custom APIs
summary: Create a Custom API
operationId: CreateACustomAPI
description: Create a Custom API
requestBody:
$ref: '#/components/requestBodies/CreateCustomAPI'
responses:
'201':
$ref: '#/components/responses/CustomAPI'
'400':
$ref: '#/components/responses/ValidationError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
get:
tags:
- Custom APIs
summary: List Custom APIs
operationId: ListCustomAPIs
description: 'Retrieves a list of Custom APIs
## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Custom APIs:
| Attribute | Operators | Example |
|---------------------|-------------------------------|-----------------------------------------------|
| `id` | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,7e067539-6f6c-46e1-8c55-940031b36c6a)` |
| `created_at` | `lt`,`le`,`eq`,`gt`,`ge` | `ge(created_at,2024-04-29T00:00:00.000Z)` |
| `updated_at` | `lt`,`le`,`eq`,`gt`,`ge` | `le(updated_at,2024-04-29T00:00:00.000Z)` |
| `api_type` | `eq`,`like`,`in` | `like(api_type,wishlist*)` |
| `description` | `eq`,`like` | `like(description,*list*)` |
| `name` | `eq`,`like` | `eq(name,"Wishlist")` |
| `slug` | `eq`,`like`,`in` | `like(slug,*lists)` |
| `presentation.page` | `ilike` | `ilike(presentation.page,Home)` |
## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`
- `api_type`
- `name`
- `slug`
'
parameters:
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/CustomAPISort'
responses:
'200':
$ref: '#/components/responses/ListOfCustomAPIs'
'400':
$ref: '#/components/responses/BadFilterError'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/settings/extensions/custom-apis/{custom-api-id}:
parameters:
- $ref: '#/components/parameters/CustomAPIID'
get:
tags:
- Custom APIs
summary: Get a Custom API
operationId: GetACustomApi
description: Get a Custom API
responses:
'200':
$ref: '#/components/responses/CustomAPI'
'400':
$ref: '#/components/responses/ValidationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
put:
tags:
- Custom APIs
summary: Update a Custom API
operationId: UpdateACustomApi
description: Update a Custom API
requestBody:
$ref: '#/components/requestBodies/UpdateCustomAPI'
responses:
'200':
$ref: '#/components/responses/CustomAPI'
'400':
$ref: '#/components/responses/ValidationError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
tags:
- Custom APIs
summary: Delete a Custom API
operationId: DeleteACustomApi
description: Delete a Custom API
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/ValidationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/settings/extensions/specifications/openapi:
get:
tags:
- Custom APIs
summary: Get OpenAPI Specification
operationId: GetOpenAPISpecification
description: 'Generates an OpenAPI specification based on the Custom APIs and Custom Fields configured for the current store.
This dynamically generated specification provides typed schemas for the `/v2/extensions/` endpoints.
'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: The OpenAPI specification in JSON format.
additionalProperties: true
'400':
$ref: '#/components/responses/ValidationError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
PageOffset:
name: page[offset]
description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.
in: query
required: false
schema:
type: integer
format: int64
minimum: 0
maximum: 10000
example: 0
Filter:
name: filter
in: query
required: false
description: Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.
schema:
type: string
format: string
example: eq(name,"My Wishlist")
PageLimit:
name: page[limit]
description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.
in: query
required: false
schema:
type: integer
format: int64
minimum: 0
example: 100
CustomAPISort:
name: sort
in: query
description: 'Specifies the order in which Custom APIs will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).
'
required: false
schema:
type: string
default: -created_at
enum:
- id
- -id
- created_at
- -created_at
- updated_at
- -updated_at
- api_type
- -api_type
- name
- -name
- slug
- -slug
example: id
x-enumDescriptions:
id: Sort by UUID string in ascending order
-id: Sort by UUID string in descending order
created_at: Sort chronologically from oldest to newest creation date
-created_at: Sort chronologically from newest to oldest creation date
updated_at: Sort chronologically from oldest to newest update date
-updated_at: Sort chronologically from newest to oldest update date
api_type: Sort API types alphabetically (A-Z)
-api_type: Sort API types reverse alphabetically (Z-A)
name: Sort names alphabetically (A-Z)
-name: Sort names reverse alphabetically (Z-A)
slug: Sort slugs alphabetically (A-Z)
-slug: Sort slugs reverse alphabetically (Z-A)
CustomAPIID:
name: custom-api-id
description: The unique identifier of the Custom API.
in: path
required: true
schema:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
requestBodies:
UpdateCustomAPI:
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- type
properties:
type:
type: string
description: Specifies the type of the resource object, use `custom_api` for Custom APIs.
const: custom_api
name:
type: string
description: Specifies the name of this Custom API.
minLength: 1
maxLength: 255
description:
type: string
description: Specifies the description for this Custom API.
minLength: 0
maxLength: 255
slug:
type: string
description: 'Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.
'
pattern: ^[a-z0-9_-]{1,63}$
allow_upserts:
type: boolean
description: 'Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn''t exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.
'
default: false
presentation:
type: object
description: Optional presentation options for the Custom API.
properties:
page:
type:
- string
- 'null'
description: The page where this Custom API should be presented. The available values depend on the deployment and may change.
section:
type:
- string
- 'null'
description: The section within the page. Can only be set when `page` is also set.
maxLength: 64
relationships:
$ref: '#/components/schemas/CustomAPIRelationships'
examples:
Update Example:
summary: Update a Custom API
value:
data:
type: custom_api
name: Wishlists
description: Specifies the description for this Custom API.
slug: wishlists
relationships:
parent_apis:
data:
- id: 652e39d8-d613-493e-8c20-fef99ad6327a
type: custom_api
CreateCustomAPI:
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- type
- name
- slug
- api_type
properties:
type:
type: string
description: Specifies the type of the resource object, use `custom_api` for Custom APIs.
const: custom_api
name:
type: string
description: Specifies the name of this Custom API.
minLength: 1
maxLength: 255
description:
type: string
description: Specifies the description for this Custom API.
minLength: 0
maxLength: 255
slug:
type: string
description: 'Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.
'
pattern: ^[a-z0-9_-]{1,63}$
api_type:
type: string
description: 'Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.
'
pattern: ^[a-z0-9_]{1,59}_ext$
allow_upserts:
type: boolean
description: 'Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn''t exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.
'
default: false
presentation:
type: object
description: Optional presentation options for the Custom API.
properties:
page:
type:
- string
- 'null'
description: The page where this Custom API should be presented. The available values depend on the deployment and may change.
section:
type:
- string
- 'null'
description: The section within the page. Can only be set when `page` is also set.
maxLength: 64
relationships:
$ref: '#/components/schemas/CustomAPIRelationships'
examples:
Create Example:
summary: Create a Custom API
value:
data:
type: custom_api
name: Wishlists
description: Specifies the description for this Custom API.
slug: wishlists
api_type: wishlist_ext
relationships:
parent_apis:
data:
- id: 652e39d8-d613-493e-8c20-fef99ad6327a
type: custom_api
responses:
NotFoundError:
description: Not found. The requested entity does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Not Found:
summary: Requested entity not found
value: "{\n \"errors\": [\n {\n \"title\": \"Not Found\",\n \"status\": \"404\",\n \"detail\": \"Not found\"\n }\n ]\n}\n"
ConflictError:
description: Unable to perform the operation at this time.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Duplicate Custom API:
summary: Duplicate Custom API
value: "{\n \"errors\": [\n {\n \"title\": \"Conflict\",\n \"status\": \"409\",\n \"detail\": \"custom_api with the given api_type already exists\"\n }\n ]\n}\n"
Duplicate Custom Field:
summary: Duplicate Custom Field
value: "{\n \"errors\": [\n {\n \"title\": \"Conflict\",\n \"status\": \"409\",\n \"detail\": \"custom_field with the given slug already exists\"\n }\n ]\n}\n"
ValidationError:
description: Bad request. The request failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Name:
summary: Required field missing
value: "{\n \"errors\": [\n {\n \"title\": \"Bad Request\",\n \"status\": \"400\",\n \"detail\": \"The field 'name' is required.\"\n }\n ]\n}\n"
CustomAPI:
description: A Custom API
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomAPI'
InternalServerError:
description: Internal server error. There was a system failure in the platform.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Internal Server Error:
summary: Internal server error
value: "{\n \"errors\": [\n {\n \"title\": \"Internal Server Error\",\n \"status\": \"500\",\n \"detail\": \"there was a problem processing your request\"\n }\n ]\n}\n"
BadFilterError:
description: Bad request. The request failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Bad Filter:
summary: Invalid field specified for filter
value: "{\n \"errors\": [\n {\n \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n \"status\": \"400\",\n \"title\": \"Bad Request\"\n }\n ]\n}\n"
ListOfCustomAPIs:
description: List of Custom APIs
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomAPI'
meta:
$ref: '#/components/schemas/PaginationMeta'
links:
$ref: '#/components/schemas/PaginationLinks'
schemas:
Timestamps:
type: object
properties:
created_at:
type: string
description: Specifies the date the entity is created.
example: '2017-01-10T11:41:19.244Z'
updated_at:
type: string
description: Specifies the date the entity is last updated.
example: '2017-01-10T11:41:19.244Z'
Meta:
type: object
properties:
timestamps:
$ref: '#/components/schemas/Timestamps'
CustomAPI:
type: object
properties:
id:
type: string
description: The unique identifier for the Custom API.
format: uuid
type:
type: string
description: Specifies the type of the resource object, use `custom_api` for Custom APIs.
const: custom_api
name:
type: string
description: Specifies the name of this Custom API.
minLength: 1
maxLength: 255
description:
type: string
description: Specifies the description for this Custom API.
minLength: 0
maxLength: 255
slug:
type: string
description: 'Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.
'
pattern: ^[a-z0-9_-]{1,63}$
api_type:
type: string
description: 'Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.
'
pattern: ^[a-z0-9_]{1,59}_ext$
allow_upserts:
type: boolean
description: 'Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn''t exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.
'
default: false
presentation:
type: object
description: Optional presentation options for the Custom API.
properties:
page:
type:
- string
- 'null'
description: The page where this Custom API should be presented. The available values depend on the deployment and may change.
section:
type:
- string
- 'null'
description: The section within the page. Can only be set when `page` is also set.
links:
type: object
properties:
self:
$ref: '#/components/schemas/LinkURI'
description: Specifies the URI of the Custom API.
example: /v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6
meta:
$ref: '#/components/schemas/Meta'
relationships:
$ref: '#/components/schemas/CustomAPIRelationships'
Errors:
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- status
- title
properties:
status:
type: string
description: The HTTP response code of the error.
format: string
examples:
- '400'
title:
type: string
description: A brief summary of the error.
examples:
- Bad Request
detail:
type: string
description: Optional additional detail about the error.
examples:
- The field 'name' is required
CustomAPIRelationships:
type: object
properties:
parent_apis:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: 'The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.
When the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.
'
example: 652e39d8-d613-493e-8c20-fef99ad6327a
type:
type: string
description: Specifies the type of parent relationship, can be `custom_api` or `api_location`.
enum:
- custom_api
- api_location
LinkURI:
type:
- string
- 'null'
format: uri
PaginationMeta:
type: object
properties:
results:
type: object
properties:
total:
type: integer
description: Total number of results for the entire collection.
total_method:
type: string
description: The method used to calculate the total number results.
enum:
- exact
- lower_bound
- observed
x-enumDescriptions:
exact: Indicates that the total is an exact count of results
lower_bound: When there are more than 10,000 results, we stop counting at 10,000 and report that the count is a lower_bound.
observed: Will indicate if there is at least one more result past the current page, this is the highest performing option as it doesn't require an extra call.
page:
type: object
properties:
limit:
type: integer
description: The maximum number of records for all pages.
example: 100
offset:
type: integer
description: The current offset by number of pages.
example: 0
current:
type: integer
description: The current number of pages.
example: 1
total:
type: integer
description: The total number of pages.
example: 1
PaginationLinks:
type: object
properties:
current:
$ref: '#/components/schemas/LinkURI'
description: Always the current page.
example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
first:
$ref: '#/components/schemas/LinkURI'
description: Always the first page.
example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
last:
$ref: '#/components/schemas/LinkURI'
description: Always `null` if there is only one page.
example: /v2/settings/custom-apis?page[offset]=0&page[limit]=100
next:
$ref: '#/components/schemas/LinkURI'
description: Always `null` if there is only one page.
example: null
prev:
$ref: '#/components/schemas/LinkURI'
description: Always `null` if on the first page.
example: null
securitySchemes:
BearerToken:
type: http
scheme: bearer