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/`. ' 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/`. ' 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/`. ' 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