Product Identifiers v3
API for managing product identifiers such as EANs/ISBNs or DOIs.
Endpoints
GET /resource/v3/products/{productId}/identifiers
List product identifiers
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
active |
query | boolean | No | Filter by active status | |
channel |
query | string | No | Filter by distribution channel (e.g., 'amazon') | |
product_format |
query | string | No | Filter by product format ('epub', 'pdf', 'mobi', 'ibooks', 'pod') | |
product_type |
query | string | No | Filter by product type ('ebook', 'book', 'audiobook', 'software') | |
productId |
path | string | No | Unique ID of the product | |
type |
query | string | No | Filter by identifier type (e.g., 'gtin13') | |
value |
query | string | No | Filter by exact identifier value (e.g EAN) |
Response 200 OK
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
Response 400 Bad Request
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
POST /resource/v3/products/{productId}/identifiers
Create a new identifier
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
productId |
path | string | No | Unique ID of the product |
Request body
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
Schema of the request body
{
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
Response 201 Created
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
Schema of the response body
{
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
Response 400 Bad Request
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
GET /resource/v3/products/{productId}/identifiers/{identifierId}
Get details of a single identifier
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
identifierId |
path | string | No | Unique ID of the product identifier | |
productId |
path | string | No | Unique ID of the product |
Response 200 OK
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
Schema of the response body
{
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
Response 404 Not Found
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
PUT /resource/v3/products/{productId}/identifiers/{identifierId}
Update a single identifier
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
identifierId |
path | string | No | Unique ID of the product identifier | |
productId |
path | string | No | Unique ID of the product |
Request body
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
Schema of the request body
{
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
Response 200 OK
{
"_id": "c927a41d-624b-45df-a2e0-0664b86e02db",
"type": "gtin13",
"product_type": "ebook",
"product_format": "epub",
"value": "9783638101417",
"channels": [
"amazon",
"itunes"
],
"active": true
}
Schema of the response body
{
"type": "object",
"required": [
"type",
"product_type",
"product_format",
"value",
"channels",
"_id",
"active"
],
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"example": "c927a41d-624b-45df-a2e0-0664b86e02db",
"nullable": true
},
"type": {
"type": "string",
"example": "gtin13"
},
"product_type": {
"type": "string",
"example": "ebook"
},
"product_format": {
"type": "string",
"nullable": true,
"example": "epub"
},
"value": {
"type": "string",
"example": "9783638101417"
},
"channels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"amazon",
"itunes"
]
},
"active": {
"type": "boolean"
}
}
}
Response 400 Bad Request
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
DELETE /resource/v3/products/{productId}/identifiers/{identifierId}
Delete an identifier
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
identifierId |
path | string | No | Unique ID of the product identifier | |
productId |
path | string | No | Unique ID of the product |
Response 204 No Content