Sales Reports v3
Endpoint to upload sales reports and view the status of their processing.
Endpoints
GET /resource/v3/sales_reports
Retrieve a list of sales reports
Response 200 OK
{
"links": {},
"items": [
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/sales_reports/072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"created": 1744119515,
"error": null,
"file_name": "gxyde-amazon-us-reseller.txt",
"file_size": 498098498,
"href": "https://api.openpublishing.com/rpc/sales_importer_download....",
"labels": [],
"mime_type": "application/octet-stream",
"module": "amazonsalespreview",
"processed": true,
"properties": {},
"realm": {
"_id": 23,
"_links": {
"self": "https://api.openpublishing.com/resource/v3/realms/0e1b578b-b998-427d-8a0c-6c09eeba91d6"
},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
]
}
Schema of the response body
{
"type": "object",
"properties": {
"links": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "string",
"description": "Link to the sales report resource",
"example": "https://api.openpublishing.com/resource/v3/sales_reports/072d54f7-00d6-42ee-96de-0d7689d1ea3b"
}
}
},
"created": {
"type": "integer",
"description": "The timestamp when the report was created",
"example": 1744119515
},
"error": {
"type": "string",
"description": "Any error associated with the report, if applicable",
"nullable": true,
"example": null
},
"file_name": {
"type": "string",
"description": "The file name of the report",
"example": "gxyde-amazon-us-reseller.txt"
},
"file_size": {
"type": "integer",
"description": "The size of the file in bytes",
"example": 498098498
},
"href": {
"type": "string",
"description": "URL to download the sales report",
"example": "https://api.openpublishing.com/rpc/sales_importer_download...."
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels associated with the report",
"example": []
},
"mime_type": {
"type": "string",
"description": "MIME type of the file",
"example": "application/octet-stream"
},
"module": {
"type": "string",
"description": "The module from which the sales report was generated",
"example": "amazonsalespreview"
},
"processed": {
"type": "boolean",
"description": "Indicates whether the report has been processed",
"example": true
},
"properties": {
"type": "object",
"description": "Additional properties related to the report",
"example": {}
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"properties": {
"_id": {
"type": "int",
"description": "Realm ID",
"example": 23
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "string",
"description": "Link to the realm resource",
"example": "https://api.openpublishing.com/resource/v3/realms/0e1b578b-b998-427d-8a0c-6c09eeba91d6"
}
}
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
}
},
"sha1": {
"type": "string",
"description": "SHA1 hash of the file",
"example": "dfb107aec15dd73f0ce8392e1c7989c6723fc861"
},
"type": {
"type": "string",
"description": "Type of the sales report",
"example": "sales_report"
}
}
}
}
}
}
POST /resource/v3/sales_reports
Upload a new sales report. A description of the generic sales report format can be found below
Request body
{
"file": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
}
Schema of the request body
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload"
}
}
}
GET /resource/v3/sales_reports/{id}
Retrieve a single sales report by ID
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the sales report |
Response 200 OK
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/sales_reports/072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"created": 1744119515,
"error": null,
"file_name": "gxyde-amazon-us-reseller.txt",
"file_size": 498098498,
"href": "https://api.openpublishing.com/rpc/sales_importer_download....",
"labels": [],
"mime_type": "application/octet-stream",
"module": "amazonsalespreview",
"processed": true,
"properties": {},
"realm": {
"_id": 23,
"_links": {
"self": "https://api.openpublishing.com/resource/v3/realms/0e1b578b-b998-427d-8a0c-6c09eeba91d6"
},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
Schema of the response body
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "string",
"description": "Link to the sales report resource",
"example": "https://api.openpublishing.com/resource/v3/sales_reports/072d54f7-00d6-42ee-96de-0d7689d1ea3b"
}
}
},
"created": {
"type": "integer",
"description": "The timestamp when the report was created",
"example": 1744119515
},
"error": {
"type": "string",
"description": "Any error associated with the report, if applicable",
"nullable": true,
"example": null
},
"file_name": {
"type": "string",
"description": "The file name of the report",
"example": "gxyde-amazon-us-reseller.txt"
},
"file_size": {
"type": "integer",
"description": "The size of the file in bytes",
"example": 498098498
},
"href": {
"type": "string",
"description": "URL to download the sales report",
"example": "https://api.openpublishing.com/rpc/sales_importer_download...."
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels associated with the report",
"example": []
},
"mime_type": {
"type": "string",
"description": "MIME type of the file",
"example": "application/octet-stream"
},
"module": {
"type": "string",
"description": "The module from which the sales report was generated",
"example": "amazonsalespreview"
},
"processed": {
"type": "boolean",
"description": "Indicates whether the report has been processed",
"example": true
},
"properties": {
"type": "object",
"description": "Additional properties related to the report",
"example": {}
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"properties": {
"_id": {
"type": "int",
"description": "Realm ID",
"example": 23
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "string",
"description": "Link to the realm resource",
"example": "https://api.openpublishing.com/resource/v3/realms/0e1b578b-b998-427d-8a0c-6c09eeba91d6"
}
}
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
}
},
"sha1": {
"type": "string",
"description": "SHA1 hash of the file",
"example": "dfb107aec15dd73f0ce8392e1c7989c6723fc861"
},
"type": {
"type": "string",
"description": "Type of the sales report",
"example": "sales_report"
}
}
}
Schemas
Sales Report
| Name | Type |
|---|---|
_id |
string Unique identifier for the sales report
Example: |
_links |
Properties: self |
created |
integer The timestamp when the report was created
Example: |
error |
string| null Any error associated with the report, if applicable |
file_name |
string The file name of the report
Example: |
file_size |
integer The size of the file in bytes
Example: |
href |
string URL to download the sales report
Example: |
labels |
Array<string> |
mime_type |
string MIME type of the file
Example: |
module |
string The module from which the sales report was generated
Example: |
processed |
boolean Indicates whether the report has been processed
Example: |
properties |
Additional properties related to the report |
realm |
Properties: _id, _links, name, screennameReference to realm which owns this object |
sha1 |
string SHA1 hash of the file
Example: |
type |
string Type of the sales report
Example: |
Generic CSV Format
When uploading Sales via CSV format, provided CSV may have the following columns:
| Column Name | Description |
|---|---|
| ISBN | Isbn or EAN of the sold product. |
| QUANTITY | Quantity, defaults to 1 of not set. |
| TYPE | either ebook or book. |
| RETAIL_PRICE_NET | Retail price of sold item, without VAT, for single item. |
| RETAIL_PRICE_NET_CURRENCY | Currency of RETAIL_PRICE_NET. |
| RETAIL_PRICE_GROSS | Retail price of sold item, with VAT, for single item. |
| RETAIL_PRICE_GROSS_CURRENCY | Currency of RETAIL_PRICE_GROSS. |
| SALES_DATE | Date at which the sale occurred. |
| AMOUNT_RECEIVED_NET | Amount received by publisher. |
| AMOUNT_RECEIVED_NET_CURRENCY | Currency of AMOUNT_RECEIVED_NET. |
| VAT_PERCENTAGE | VAT percentage with which the sale should be booked. |
| SALES_CHANNEL | Shop outlet in which the product was sold. |
| DISTRIBUTOR | Main distribution channel through which the product was sold. |