{ "openapi": "3.1.0", "info": { "title": "Auction Plus API Documentation", "version": "1.0.0", "description": "The Auction Plus REST API.\n\nThis guide provides the technical specifications, authentication procedures, and endpoint definitions necessary to integrate with the Auction Plus API.\n\n## Rate Limiting\n\nThe API uses a leaky bucket algorithm to control request rates. Each authenticated user has a bucket with a capacity of **60 requests**. The bucket leaks at a rate of **4 requests per second**.\n\nWhen a request is made, it is added to the bucket. If the bucket is full, the API responds with a `429 Too Many Requests` status.\n\n### Response Headers\n\nEvery response includes rate limit headers:\n\n| Header | Description |\n|---|---|\n| `X-RateLimit-Limit` | Maximum number of requests (bucket capacity) |\n| `X-RateLimit-Remaining` | Number of requests remaining in the bucket |\n\nWhen rate limited (429), additional headers are included:\n\n| Header | Description |\n|---|---|\n| `Retry-After` | Seconds to wait before retrying |\n| `X-RateLimit-Reset` | Unix timestamp when the bucket resets |" }, "servers": [ { "url": "https://api.auctionplusapp.com/v1" } ], "tags": [ { "name": "Auction Items", "description": "An auction item represents a single listing in an auction. Each item has a **status** of `scheduled`, `active`, or `completed`. Canceled auctions are indicated by a non-null **canceledAt** timestamp.\n\nPrice attributes such as **startPrice**, **reservePrice**, **minimumBid**, **currentIncrement**, and **highBidAmount** are returned as a price object containing **value** (minor units), **major**, **display**, and **currency** fields.\n\nThe **bidIncrementStrategy** describes the increment type \u2014 `fixed_amount`, `percentage`, or `tier` \u2014 along with a **value** object containing the increment details.\n\nThe **softClose** object indicates whether soft close is enabled. When active, **extendFrom** specifies how many seconds before the end time a bid triggers an extension, and **extendDuration** specifies how many seconds the auction is extended by.\n\nThe **processed** attribute indicates whether the auction listing has been finalized, including assigning a winner. Listings are typically processed within a minute after the end time." } ], "security": [ { "http": [] } ], "paths": { "/auction-items": { "get": { "operationId": "listAuctionItems", "description": "Returns a paginated list of auction items.", "summary": "List Auction Items", "tags": [ "Auction Items" ], "parameters": [ { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "active", "scheduled", "completed" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`, `sku`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[customers]", "in": "query", "description": "Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `maxBid`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with `-` for descending order. Available values: `endsAt`, `-endsAt`, `totalBids`, `-totalBids`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "maxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/VariantResource" }, { "$ref": "#/components/schemas/ProductResource" }, { "$ref": "#/components/schemas/BidResource" }, { "$ref": "#/components/schemas/CustomerResource" }, { "$ref": "#/components/schemas/MaxBidResource" } ] } } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auction-items/{id}": { "get": { "operationId": "getAuctionItem", "description": "Retrieve the details for a single auction listing.", "summary": "Retrieve an auction item", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`, `sku`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[customers]", "in": "query", "description": "Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item ID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `maxBid`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "maxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/VariantResource" }, { "$ref": "#/components/schemas/ProductResource" }, { "$ref": "#/components/schemas/BidResource" }, { "$ref": "#/components/schemas/CustomerResource" }, { "$ref": "#/components/schemas/MaxBidResource" } ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auction-items/{id}/end": { "patch": { "operationId": "endAuctionItem", "description": "Ends an active or scheduled listing early.", "summary": "End an auction listing", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[customers]", "in": "query", "description": "Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `highBid`, `highBid.customer`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/BidResource" }, { "$ref": "#/components/schemas/CustomerResource" } ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "description": "This auction item has already ended.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "example": { "errors": [ { "status": "422", "code": "auction_ended", "detail": "This auction item has already ended." } ] }, "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }, "/auction-items/{id}/cancel": { "patch": { "operationId": "cancelAuctionItem", "description": "Cancels a listing without assigning a winner.", "summary": "Cancel an auction listing", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[customers]", "in": "query", "description": "Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `highBid`, `highBid.customer`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/BidResource" }, { "$ref": "#/components/schemas/CustomerResource" } ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "description": "Unprocessable entity", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "422", "code": "auction_canceled", "detail": "This auction item has already been canceled." } ] }, { "errors": [ { "status": "422", "code": "auction_processed", "detail": "This auction item has already been processed." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }, "/auction-items/{id}/place-bid": { "post": { "operationId": "placeBid", "description": "Places a bid on an active auction item.\n\nYou must provide either **max_amount** for a maximum bid (automatic bidding), **amount** for a straight bid, or both.\n\n- **Straight bid** (`amount`): Places a single bid at the specified amount.\n- **Proxy bid** (`max_amount`): Sets the maximum amount the system will automatically bid up to on behalf of the customer. The system places the minimum winning bid and automatically increments as competing bids are received, up to the maximum.\n- **Both** (`amount` + `max_amount`): Places a straight bid at the specified amount and sets a proxy maximum for automatic bidding.\n\nThe response returns the updated **auction item** with a `meta.status` field indicating whether the customer is the `high_bidder` or was automatically `outbid` by proxy bidding.", "summary": "Place a bid", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[customers]", "in": "query", "description": "Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `highBid`, `highBid.customer`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "The customer UID." }, "amount": { "type": [ "number", "null" ], "description": "The bid amount in major currency units (e.g. 10.50).", "minimum": 0 }, "maxAmount": { "type": [ "number", "null" ], "description": "The maximum (proxy) bid in major currency units (e.g. 10.50).", "minimum": 0 } }, "required": [ "customerId" ] } } } }, "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/BidResource" }, { "$ref": "#/components/schemas/CustomerResource" } ] } }, "meta": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "outbid", "high_bidder" ] } }, "required": [ "status" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "description": "The bid could not be placed. Inspect `errors[0].code` for the specific reason:\n\n- `user_not_found` \u2014 customer was not found for the given `customerId`.\n- `auction_ended` \u2014 the auction has already ended.\n- `amount_below_start_price` \u2014 the straight bid `amount` is below the auction's start price.\n- `amount_below_showing_bid` \u2014 the straight bid `amount` is at or below the current high bid plus the required increment. `meta.minimum_bid` shows the minimum acceptable value.\n- `max_amount_below_start_price` \u2014 the max bid `maxAmount` is below the auction's start price. `meta.minimum_bid` shows the start price.\n- `max_amount_below_showing_bid` \u2014 the max bid `maxAmount` is at or below the current high bid plus the required increment. `meta.minimum_bid` shows the minimum acceptable value.\n- `max_amount_below_current_bid` \u2014 the customer is already the high bidder and the new `maxAmount` is lower than their existing showing bid. `meta.minimum_bid` shows the existing bid amount.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "example": { "errors": [ { "status": "422", "code": "validation_error", "detail": "The selected field is invalid.", "source": { "parameter": "field_name" }, "meta": { "rule": "required" } } ] }, "examples": [ { "errors": [ { "status": "422", "code": "user_not_found", "detail": "The provided user was not found.", "source": { "parameter": "customerId" } } ] }, { "errors": [ { "status": "422", "code": "auction_ended", "detail": "This auction has ended and bids are no longer being accepted." } ] }, { "errors": [ { "status": "422", "code": "amount_below_start_price", "detail": "The amount must be greater than the start price." } ] }, { "errors": [ { "status": "422", "code": "amount_below_showing_bid", "detail": "The amount must be greater than the leading bid plus the bid increment.", "meta": { "minimum_bid": "55.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_start_price", "detail": "The max bid amount must be greater than the start price.", "meta": { "minimum_bid": "1.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_showing_bid", "detail": "The max bid amount must be greater than or equal to the showing bid plus the bid increment.", "meta": { "minimum_bid": "55.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_current_bid", "detail": "The max bid amount must be greater than or equal to the current bid.", "meta": { "minimum_bid": "50.00" } } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "403": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "example": { "errors": [ { "status": "403", "code": "access_denied", "detail": "The provided user does not have access to this resource." } ] }, "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "You can retrieve your token by visiting Settings > API and clicking Generate API token.", "scheme": "bearer" } }, "schemas": { "AuctionItemResource": { "type": "object", "example": { "id": "ak5m7g21ys3q329atnctgznta0", "type": "auction-items", "attributes": { "startPrice": { "value": 100, "major": "1.00", "display": "$1.00", "currency": "USD" }, "reservePrice": { "value": 1000, "major": "10.00", "display": "$10.00", "currency": "USD" }, "bidIncrementStrategy": { "strategy": "fixed_amount", "value": { "amount": { "value": 500, "major": "5.00", "display": "$5.00", "currency": "USD" } } }, "automaticBidding": { "enabled": true }, "softClose": { "enabled": false, "extendFrom": null, "extendDuration": null }, "totalBids": 1, "highBidAmount": { "value": 5000, "major": "50.00", "display": "$50.00", "currency": "USD" }, "minimumBid": { "value": 5500, "major": "55.00", "display": "$55.00", "currency": "USD" }, "currentIncrement": { "value": 500, "major": "5.00", "display": "$5.00", "currency": "USD" }, "startsAt": "2026-06-26T13:46:34.000000Z", "endsAt": "2026-06-26T14:46:34.000000Z", "status": "active", "reserveMet": true, "canceledAt": null, "archivedAt": null, "processed": false, "createdAt": "2026-06-26T13:46:34.000000Z", "updatedAt": "2026-06-26T13:46:34.000000Z" } }, "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "auction-items" }, "attributes": { "type": "object", "properties": { "startPrice": { "$ref": "#/components/schemas/Money" }, "reservePrice": { "$ref": "#/components/schemas/Money" }, "bidIncrementStrategy": { "$ref": "#/components/schemas/BidIncrementStrategy" }, "automaticBidding": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "softClose": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "extendFrom": { "type": [ "integer", "null" ] }, "extendDuration": { "type": [ "integer", "null" ] } }, "required": [ "enabled", "extendFrom", "extendDuration" ] }, "totalBids": { "type": "integer" }, "highBidAmount": { "$ref": "#/components/schemas/Money" }, "minimumBid": { "$ref": "#/components/schemas/Money" }, "currentIncrement": { "$ref": "#/components/schemas/Money" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "reserveMet": { "type": "string" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "processed": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "required": [ "id", "type" ], "title": "AuctionItemResource" }, "BidIncrementStrategy": { "type": "object", "properties": { "strategy": { "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/FixedAmountBidIncrement" }, { "$ref": "#/components/schemas/PercentageBidIncrement" }, { "$ref": "#/components/schemas/TierBidIncrement" } ] } }, "required": [ "strategy", "value" ], "title": "BidIncrementStrategy" }, "BidResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "bids" }, "attributes": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "placedAt": { "type": [ "string", "null" ], "format": "date-time" }, "automatic": { "type": [ "boolean", "null" ] } } } }, "required": [ "id", "type" ], "title": "BidResource" }, "CustomerResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "customers" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "registeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bannedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "required": [ "id", "type" ], "title": "CustomerResource" }, "FixedAmountBidIncrement": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "value": { "type": "integer" }, "major": { "type": "string" }, "display": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "value", "major", "display", "currency" ] } }, "required": [ "amount" ], "title": "FixedAmountBidIncrement" }, "MaxBidResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "max-bids" }, "attributes": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "required": [ "id", "type" ], "title": "MaxBidResource" }, "Money": { "type": "object", "properties": { "value": { "type": "integer" }, "major": { "type": "string" }, "display": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "value", "major", "display", "currency" ], "title": "Money" }, "PercentageBidIncrement": { "type": "object", "properties": { "percentage": { "type": "number" } }, "required": [ "percentage" ], "title": "PercentageBidIncrement" }, "ProductResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "products" }, "attributes": { "type": "object", "properties": { "externalId": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "vendor": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "photoUrl": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] } } } }, "required": [ "id", "type" ], "title": "ProductResource" }, "TierBidIncrement": { "type": "object", "properties": { "tier": { "type": "string" } }, "required": [ "tier" ], "title": "TierBidIncrement" }, "VariantResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "variants" }, "attributes": { "type": "object", "properties": { "externalId": { "type": [ "integer", "null" ] }, "displayName": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ] }, "photoUrl": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] } } } }, "required": [ "id", "type" ], "title": "VariantResource" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/vnd.api+json": { "schema": { "type": "object", "example": { "errors": [ { "status": "401", "code": "unauthenticated", "detail": "Unauthenticated." } ] }, "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "example": { "errors": [ { "status": "422", "code": "validation_error", "detail": "The selected field is invalid.", "source": { "parameter": "field_name" }, "meta": { "rule": "required" } } ] }, "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }