openapi: 3.1.0
info:
title: Vendure Admin API
version: '3.6'
description: |
The Vendure Admin API is the privileged GraphQL endpoint used by the
Vendure Dashboard and back-office tooling. It governs catalogue (products,
variants, options, collections, facets), orders and fulfillment,
customers and customer groups, channels and sellers, promotions, tax
categories and rates, zones and countries, payment and shipping methods,
administrators and roles, API keys, jobs and scheduled tasks, stock
locations, assets, and global settings.
This OpenAPI document models the single GraphQL endpoint
(`POST /admin-api`); per-operation contracts are defined by the GraphQL
schema. See the reference documentation for query and mutation lists.
contact:
name: Vendure
url: https://docs.vendure.io/reference/graphql-api/admin/queries/
license:
name: GPL-3.0
url: https://github.com/vendurehq/vendure/blob/master/LICENSE
servers:
- url: http://localhost:3000/admin-api
description: Default development server
- url: https://{host}/admin-api
description: Self-hosted production server
variables:
host:
default: admin.example.com
paths:
/:
post:
summary: Execute Admin API GraphQL Operation
operationId: executeAdminGraphQL
description: |
Executes a GraphQL query, mutation, or named operation against the
Admin API. The caller must be authenticated as an administrator
whose role grants the relevant permission(s).
Permissions checked include: `CreateCatalog`, `ReadCatalog`,
`UpdateCatalog`, `DeleteCatalog`, `CreateOrder`, `ReadOrder`,
`UpdateOrder`, `DeleteOrder`, `CreateCustomer`, `ReadCustomer`,
`UpdateCustomer`, `DeleteCustomer`, `CreatePromotion`,
`ReadPromotion`, `UpdatePromotion`, `DeletePromotion`,
`CreateAdministrator`, `ReadAdministrator`, `UpdateAdministrator`,
`DeleteAdministrator`, `CreateSettings`, `ReadSettings`,
`UpdateSettings`, `DeleteSettings`.
Common operations:
- Queries: `products`, `product`, `productVariants`,
`productVariant`, `collections`, `collection`, `orders`,
`order`, `customers`, `customer`, `customerGroups`, `channels`,
`promotions`, `promotionConditions`, `promotionActions`,
`taxCategories`, `taxRates`, `zones`, `countries`,
`administrators`, `roles`, `paymentMethods`, `shippingMethods`,
`jobs`, `scheduledTasks`, `globalSettings`, `apiKeys`,
`stockLocations`, `assets`, `facets`, `sellers`.
- Mutations: `createProduct`, `updateProduct`, `deleteProduct`,
`addOptionGroupToProduct`, `createProductVariants`,
`updateProductVariants`, `assignProductsToChannel`,
`setOrderShippingAddress`, `addManualPaymentToOrder`,
`transitionOrderToState`, `cancelOrder`, `refundOrder`,
`createCustomer`, `createPromotion`, `updatePromotion`,
`createChannel`, `createTaxRate`, `createZone`,
`createPaymentMethod`, `createShippingMethod`,
`createAdministrator`, `createRole`, `cancelJob`,
`updateGlobalSettings`, `createApiKey`.
parameters:
- $ref: '#/components/parameters/AuthTokenHeader'
- $ref: '#/components/parameters/ChannelTokenHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLRequest'
examples:
listOrders:
summary: List recent orders
value:
query: |
query Orders($options: OrderListOptions) {
orders(options: $options) {
items { id code state totalWithTax customer { emailAddress } }
totalItems
}
}
variables:
options:
take: 25
sort: { createdAt: DESC }
createProduct:
summary: Create a product
value:
query: |
mutation CreateProduct($input: CreateProductInput!) {
createProduct(input: $input) { id name slug }
}
variables:
input:
translations:
- { languageCode: en, name: Demo, slug: demo, description: Demo product }
responses:
'200':
description: GraphQL response (may contain `data` and/or `errors`).
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
'401':
description: Unauthorized — missing or invalid credentials.
'403':
description: Forbidden — administrator lacks required permission.
components:
parameters:
AuthTokenHeader:
name: Authorization
in: header
required: true
description: |
Bearer token issued by the Admin `login` mutation, or session cookie
equivalent. Header name and scheme are configurable via
`authOptions.tokenMethod`.
schema:
type: string
example: Bearer eyJhbGciOi...
ChannelTokenHeader:
name: vendure-token
in: header
required: false
description: Channel token selecting the active Channel for the request.
schema:
type: string
schemas:
GraphQLRequest:
type: object
required: [query]
properties:
query: { type: string }
variables:
type: object
additionalProperties: true
operationName:
type: string
GraphQLResponse:
type: object
properties:
data:
type: object
additionalProperties: true
nullable: true
errors:
type: array
items:
type: object
properties:
message: { type: string }
path:
type: array
items:
oneOf:
- type: string
- type: integer
extensions:
type: object
additionalProperties: true
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
CookieAuth:
type: apiKey
in: cookie
name: session
ChannelToken:
type: apiKey
in: header
name: vendure-token
security:
- BearerAuth: []
ChannelToken: []
- CookieAuth: []
ChannelToken: []
tags:
- name: Catalog
- name: Orders
- name: Customers
- name: Channels
- name: Promotions
- name: Settings
- name: Jobs