Batch APIs enable a user to create, update, delete listings in bulk. Batch APIs are asynchronous in nature and we provide mechanisms to poll the API so that you can keep track of the batch completion. Once a batch is successfully completed, you can view the status of each individual listing. We track each individual listing inside a batch separately so you can have scenarios where some listings succeed and some fail in a single batch.
openapi: 3.0.0
info:
title: StockX Public Batch API
version: 2.0.0
description: Manage StockX seller account using APIs
license:
name: MIT
contact: {}
servers:
- url: https://api.stockx.com/v2
tags:
- name: Batch
description: Batch APIs enable a user to create, update, delete listings in bulk. Batch APIs are asynchronous in nature and we provide mechanisms to poll the API so that you can keep track of the batch completion. Once a batch is successfully completed, you can view the status of each individual listing. We track each individual listing inside a batch separately so you can have scenarios where some listings succeed and some fail in a single batch.
paths:
/selling/batch/create-listing:
post:
operationId: CreateListings
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateListingResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: Create a new batch of listings
summary: Batch listings creation
tags:
- Batch
security:
- api_key: []
jwt: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreateListingInput'
/selling/batch/create-listing/{batchId}:
get:
operationId: GetListingCreateBatch
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingCreateBatchResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once you are able to create a batch successfully, you need to poll the get batch status API to track the progress of the batch.
This polling is necessary because all batch operations are asynchronous in nature.'
summary: Batch listings creation - Get Batch Status
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: Unique Batch ID
in: path
name: batchId
required: true
schema:
type: string
/selling/batch/create-listing/{batchId}/items:
get:
operationId: GetListingCreateBatchItems
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingCreateBatchItemsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once a batch completes successfully, you need to use the get batch items API to see the results of each item in the batch.
You can also use this API at any point in time after the batch is created to see the progress of each individual item in a batch.'
summary: Batch listings creation - Get Items
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: The ID of batch
in: path
name: batchId
required: true
schema:
type: string
- description: Status of listing
in: query
name: status
required: false
schema:
type: string
example: COMPLETED
/selling/batch/delete-listing:
post:
operationId: DeleteListings
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDeleteListingResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Batch delete listings API allows a user to delete up to 100 individual listings in a single API call.
This API is asynchronous in nature and will return a batchId that you would need to poll using the polling APIs described later.'
summary: Batch listings deletion
tags:
- Batch
security:
- api_key: []
jwt: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDeleteListingInput'
/selling/batch/delete-listing/{batchId}:
get:
operationId: GetListingDeleteBatch
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingDeleteBatchResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once you are able to create a batch successfully, you need to poll the get batch status API to track the progress of the batch.
This polling is necessary because all batch operations are asynchronous in nature.'
summary: Batch listings deletion - Get Batch Status
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: Unique Batch ID
in: path
name: batchId
required: true
schema:
type: string
/selling/batch/delete-listing/{batchId}/items:
get:
operationId: GetListingDeleteBatchItems
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingDeleteBatchItemsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once a batch completes successfully, you need to use the get batch items API to see the results of each item in the batch.
You can also use this API at any point in time after the batch is created to see the progress of each individual item in a batch.'
summary: Batch listings deletion - Get Items
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: Unique Batch ID
in: path
name: batchId
required: true
schema:
type: string
- in: query
name: status
required: false
schema:
type: string
example: COMPLETED
/selling/batch/update-listing:
post:
operationId: UpdateListings
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdateListingResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Batch update listings API allows a user to update up to 100 individual listings in a single API call.
This API is asynchronous in nature and will return a batchId that you would need to poll using the polling APIs described later.'
summary: Batch listings update
tags:
- Batch
security:
- api_key: []
jwt: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdateListingInput'
/selling/batch/update-listing/{batchId}:
get:
operationId: GetListingUpdateBatch
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingUpdateBatchResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once you are able to create a batch successfully, you need to poll the get batch status API to track the progress of the batch.
This polling is necessary because all batch operations are asynchronous in nature.'
summary: Batch listings update - Get Batch Status
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: Unique Batch ID
in: path
name: batchId
required: true
schema:
type: string
/selling/batch/update-listing/{batchId}/items:
get:
operationId: GetListingUpdateBatchItems
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetListingUpdateBatchItemsResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
description: 'Once a batch completes successfully, you need to use the get batch items API to see the results of each item in the batch.
You can also use this API at any point in time after the batch is created to see the progress of each individual item in a batch'
summary: Batch listings update - Get Items
tags:
- Batch
security:
- api_key: []
jwt: []
parameters:
- description: Unique Batch ID
in: path
name: batchId
required: true
schema:
type: string
- description: Status of listing
in: query
name: status
required: false
schema:
type: string
example: COMPLETED
components:
schemas:
UUID:
type: string
example: bf364c53-eb77-4522-955c-6a6ce952cc6f
description: 'Stringified UUIDv4.
See [RFC 4112](https://tools.ietf.org/html/rfc4122)'
pattern: '[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}'
GetListingUpdateBatchResponse:
properties:
batchId:
type: string
description: Unique Batch ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of the batch
example: QUEUED
completedAt:
type: string
nullable: true
description: When this batch was completed in UTC. Represented as ISO 8601 format like 2022-01-18T20:20:39Z
example: '2021-11-09T12:44:31.000Z'
createdAt:
type: string
description: When this batch was created in UTC. Represented as ISO 8601 format like 2022-01-18T20:20:39Z
example: '2021-11-09T12:44:31.000Z'
updatedAt:
type: string
description: When this batch was updated in UTC. Represented as ISO 8601 format like 2022-01-18T20:20:39Z
example: '2021-11-09T12:44:31.000Z'
totalItems:
type: number
format: double
description: Total number of items in this batch
example: 10
itemStatuses:
$ref: '#/components/schemas/BatchStatusCounts'
description: The number of items in this batch grouped by their statuses. This is a short-hand way to quickly introspect how many items are still enqued, how many succeeded or how many failed in a batch
required:
- batchId
- status
- completedAt
- createdAt
- updatedAt
- totalItems
- itemStatuses
type: object
additionalProperties: false
UpdateBatchListingRequestItem:
properties:
listingId:
type: string
description: Unique listing ID that needs to be updated
example: 98e2e748-8000-45bf-a624-5531d6a68318
amount:
type: string
description: The amount this Listing is updated to
example: 79
expiresAt:
type: string
description: UTC timestamp representing the Listing expiry date that is being updated to
example: '2021-11-09T12:44:31.000Z'
currencyCode:
type: string
description: 'The currency this Listing is updated to<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
example: USD
active:
type: boolean
description: Flag used to indicate that the listing should be active or not
example: true
required:
- listingId
type: object
additionalProperties: false
CreateBatchListingRequestItem:
properties:
inventoryType:
type: string
description: 'The inventory this product is being listed in. If not provided, it will default to STANDARD.<br><br>Available values: "STANDARD", "DIRECT"'
example: STANDARD
active:
type: boolean
description: Flag used to indicate that the listing should be active or not
example: true
quantity:
type: number
format: double
description: The total number of Listings that need to be created.
example: 10
currencyCode:
type: string
description: 'The currency this Listing is being listed in. If not provided, it will default to USD.<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
example: USD
variantId:
type: string
description: Unique StockX variant ID that this Listing is being created for
example: 98e2e748-8000-45bf-a624-5531d6a68318
expiresAt:
type: string
description: UTC timestamp representing when this Listing should auto-expire. If not provided, it will default to 999 days from today. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
amount:
type: string
description: The amount this Listing is being listed for
example: '79'
required:
- quantity
- variantId
- amount
type: object
BatchUpdateListingInput:
properties:
items:
items:
$ref: '#/components/schemas/UpdateBatchListingRequestItem'
type: array
description: An array of items that should be associated with the batch
required:
- items
type: object
additionalProperties: false
BatchDeleteListingInput:
properties:
items:
items:
$ref: '#/components/schemas/DeleteBatchListingRequestItem'
type: array
description: An array of IDs that should be associated with the batch
required:
- items
type: object
additionalProperties: false
GetListingUpdateBatchItemsResponse:
properties:
items:
items:
$ref: '#/components/schemas/GetListingUpdateBatchItem'
type: array
description: An array of items associated with the listing
required:
- items
type: object
additionalProperties: false
GetListingCreateBatchResponse:
properties:
batchId:
$ref: '#/components/schemas/UUID'
description: Unique Batch ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of this batch
example: QUEUED
completedAt:
type: string
nullable: true
description: When this batch fully completed. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
createdAt:
type: string
description: When this batch was created. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
updatedAt:
type: string
description: When this batch was last updated. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
totalItems:
type: number
format: double
description: Total number of items in this batch
example: 10
itemStatuses:
$ref: '#/components/schemas/BatchStatusCounts'
description: 'The number of items in this batch grouped by their statuses.
This is a short-hand way to quickly introspect how many items are still enqued, how many succeeded or how many failed in a batch'
example: IN_PROGRESS
required:
- batchId
- status
- completedAt
- createdAt
- updatedAt
- totalItems
- itemStatuses
type: object
additionalProperties: false
DeleteBatchListingRequestItem:
properties:
listingId:
type: string
description: Unique listing ID that needs to be deleted
example: 98e2e748-8000-45bf-a624-5531d6a68318
required:
- listingId
type: object
additionalProperties: false
BatchCreateListingResponse:
properties:
batchId:
type: string
description: Unique Batch ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of the batch
example: QUEUED
completedAt:
type: string
nullable: true
description: When the batch fully completed
example: '2021-11-09T12:44:31.000Z'
createdAt:
type: string
description: when this batch was created in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
updatedAt:
type: string
description: When this batch was last updated in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
totalItems:
type: number
format: double
description: Total number of items in this batch
example: 10
itemStatuses:
$ref: '#/components/schemas/BatchStatusCounts'
description: 'The number of items in this batch grouped by their statuses.
This is a short-hand way to quickly introspect how many items are still enqued, how many succeeded or how many failed in a batch.'
required:
- batchId
- status
- completedAt
- createdAt
- updatedAt
- totalItems
- itemStatuses
type: object
additionalProperties: false
PublicApiError:
properties:
statusCode:
$ref: '#/components/schemas/HttpStatusCodeLiteral'
description: The error status code
example: 400
message:
type: string
description: The error message
example: The request did not succeed 😭
required:
- statusCode
- message
type: object
additionalProperties: false
BatchDeleteListingResponse:
properties:
batchId:
type: string
description: Unique Batch ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of the batch
example: QUEUED
completedAt:
type: string
nullable: true
description: When this batch was completed in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
createdAt:
type: string
description: When this batch was created in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
updatedAt:
type: string
description: When this batch was updated in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
totalItems:
type: number
format: double
description: Total number of items in this batch
example: 10
itemStatuses:
$ref: '#/components/schemas/BatchStatusCounts'
description: The number of items in this batch grouped by their statuses. This is a short-hand way to quickly introspect how many items are still enqued, how many succeeded or how many failed in a batch
required:
- batchId
- status
- completedAt
- createdAt
- updatedAt
- totalItems
- itemStatuses
type: object
additionalProperties: false
HttpStatusCodeLiteral:
type: number
enum:
- 100
- 101
- 102
- 200
- 201
- 202
- 203
- 204
- 205
- 206
- 207
- 208
- 226
- 300
- 301
- 302
- 303
- 304
- 305
- 307
- 308
- 400
- 401
- 402
- 403
- 404
- 405
- 406
- 407
- 408
- 409
- 410
- 411
- 412
- 413
- 414
- 415
- 416
- 417
- 418
- 422
- 423
- 424
- 426
- 428
- 429
- 431
- 451
- 500
- 501
- 502
- 503
- 504
- 505
- 506
- 507
- 508
- 510
- 511
BatchCreateListingInput:
properties:
items:
items:
$ref: '#/components/schemas/CreateBatchListingRequestItem'
type: array
description: An array of items that should be associated with the batch
required:
- items
type: object
additionalProperties: false
GetListingUpdateBatchItem:
properties:
itemId:
type: string
description: Unique Item ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of this item
example: QUEUED
listingInput:
properties:
active:
type: boolean
nullable: true
description: Whether the listing is active or not
currencyCode:
type: string
description: 'The currency code for this listing<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
example: USD
expiresAt:
type: string
description: When this listing expires in UTC
example: '2021-11-09T12:44:31.000Z'
amount:
type: string
description: The amount this listing is listed for
example: 98e2e748-8000-45bf-a624-5531d6a68318
listingId:
type: string
description: The ID of the listing
example: 98e2e748-8000-45bf-a624-5531d6a68318
required:
- active
- listingId
type: object
description: The input for this item that was used when creating the batch
result:
properties:
askId:
type: string
nullable: true
description: The unique askId of this listing.
example: 98e2e748-8000-45bf-a624-5531d6a68318
listingId:
type: string
nullable: true
description: The unique listingId of this listing. This is a new ID being introduced that is analogous to askId
example: 98e2e748-8000-45bf-a624-5531d6a68318
required:
- askId
- listingId
type: object
description: If an item was successfully processed, the result object will contain the following
error:
type: string
description: If an item failed to process, the error attribute will contain the error message describing the reason the item failed to process
required:
- itemId
- status
- listingInput
type: object
additionalProperties: false
GetListingCreateBatchItem:
properties:
itemId:
type: string
nullable: true
description: Unique Item ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
nullable: true
description: The status of this item
example: QUEUED
listingInput:
properties:
active:
type: boolean
nullable: true
description: Whether this listing is active
currencyCode:
type: string
nullable: true
description: 'The currency code for this listing<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
example: USD
variantId:
type: string
nullable: true
description: The ID of the variant
example: 98e2e748-8000-45bf-a624-5531d6a68318
expiresAt:
type: string
nullable: true
description: When this listing expires in UTC
example: '2021-11-09T12:44:31.000Z'
amount:
type: string
nullable: true
description: The amount this listing is listed for
example: '300'
required:
- active
- currencyCode
- variantId
- expiresAt
- amount
type: object
description: The input for this item that was used when creating the batch
result:
properties:
askId:
type: string
nullable: true
description: The unique askId of this listing.
example: 98e2e748-8000-45bf-a624-5531d6a68318
listingId:
type: string
nullable: true
description: The unique listingId of this listing. This is a new ID being introduced that is analogous to askId
example: 98e2e748-8000-45bf-a624-5531d6a68318
required:
- askId
- listingId
type: object
description: 'If an item was successfully processed, the result object will contain the following:'
error:
type: string
description: If an item failed to process, the error attribute will contain the error message describing the reason the item failed to process
required:
- itemId
- status
- listingInput
type: object
additionalProperties: false
GetListingDeleteBatchItemsResponse:
properties:
items:
items:
$ref: '#/components/schemas/GetListingDeleteBatchItem'
type: array
description: An array of items associated with the listing
required:
- items
type: object
additionalProperties: false
GetListingDeleteBatchItem:
properties:
itemId:
type: string
description: Unique Item ID
example: 09f3f859-9000-56cg-a624-6642d6a68318
status:
type: string
description: The status of the task
example: IN_PROGRESS
listingInput:
properties:
id:
type: string
description: The id of target listing
required:
- id
type: object
description: The input for this item that was used when creating the batch
error:
type: string
description: If an item failed to process, the error attribute will contain the error message describing the reason the item failed to process
result:
properties:
askId:
type: string
nullable: true
description: The unique askId of this listing.
example: 09f3f859-9000-56cg-a624-6642d6a68318
listingId:
type: string
nullable: true
description: The unique listingId of this listing. This is a new ID being introduced that is analogous to askId
example: 09f3f859-9000-56cg-a624-6642d6a68318
required:
- askId
- listingId
type: object
description: 'If an item was successfully processed, the result object will contain the following:'
required:
- itemId
- status
- listingInput
type: object
additionalProperties: false
GetListingCreateBatchItemsResponse:
properties:
items:
items:
$ref: '#/components/schemas/GetListingCreateBatchItem'
type: array
description: An array of items associated with the listing
required:
- items
type: object
additionalProperties: false
BatchUpdateListingResponse:
properties:
batchId:
type: string
description: Unique Batch ID
example: 98e2e748-8000-45bf-a624-5531d6a68318
status:
type: string
description: The status of the batch
example: QUEUED
completedAt:
type: string
nullable: true
description: When this batch was last completed in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
createdAt:
type: string
description: When this batch was last created in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
example: '2021-11-09T12:44:31.000Z'
updatedAt:
type: string
description: When this batch was last updated in UTC. Represented as ISO 8601 format like 2021-11-09T12:44:31.000Z
e
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stockx/refs/heads/main/openapi/stockx-batch-api-openapi.yml