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": {},
"_pagination": {},
"items": [
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_links": {},
"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,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_links": {
"type": "object"
},
"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
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report is been deprecated (i.e. import was skipped)",
"example": false
},
"uploaded_by": {
"type": "object",
"description": "Reference to business partner who uploaded sales report",
"nullable": true
},
"uploaded_at": {
"type": "integer",
"description": "Timestamp when sales report was uploaded",
"example": 1445437680
},
"verified": {
"type": "boolean",
"description": "Indicated whether report was verfied."
},
"verified_at": {
"type": "integer",
"description": "Unix time stamp when sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verfied sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is been processed at the moment",
"example": false
},
"properties": {
"type": "object",
"description": "Additional properties related to the report",
"example": {}
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id",
"_links",
"name",
"screenname"
]
},
"sha1": {
"type": "string",
"description": "SHA1 hash of the file",
"example": "dfb107aec15dd73f0ce8392e1c7989c6723fc861"
},
"type": {
"type": "string",
"description": "Type of the sales report",
"example": "sales_report"
}
},
"required": [
"_id",
"_links",
"error",
"file_name",
"file_size",
"href",
"labels",
"mime_type",
"module",
"processed",
"deprecated",
"uploaded_by",
"uploaded_at",
"verified",
"verified_at",
"verified_by",
"in_progress",
"properties",
"realm",
"sha1",
"type"
]
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
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",
"additionalProperties": false,
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to upload"
}
},
"required": [
"file"
]
}
Response 201 Created
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_links": {},
"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,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_links": {
"type": "object"
},
"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
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report is been deprecated (i.e. import was skipped)",
"example": false
},
"uploaded_by": {
"type": "object",
"description": "Reference to business partner who uploaded sales report",
"nullable": true
},
"uploaded_at": {
"type": "integer",
"description": "Timestamp when sales report was uploaded",
"example": 1445437680
},
"verified": {
"type": "boolean",
"description": "Indicated whether report was verfied."
},
"verified_at": {
"type": "integer",
"description": "Unix time stamp when sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verfied sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is been processed at the moment",
"example": false
},
"properties": {
"type": "object",
"description": "Additional properties related to the report",
"example": {}
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id",
"_links",
"name",
"screenname"
]
},
"sha1": {
"type": "string",
"description": "SHA1 hash of the file",
"example": "dfb107aec15dd73f0ce8392e1c7989c6723fc861"
},
"type": {
"type": "string",
"description": "Type of the sales report",
"example": "sales_report"
}
},
"required": [
"_id",
"_links",
"error",
"file_name",
"file_size",
"href",
"labels",
"mime_type",
"module",
"processed",
"deprecated",
"uploaded_by",
"uploaded_at",
"verified",
"verified_at",
"verified_by",
"in_progress",
"properties",
"realm",
"sha1",
"type"
]
}
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": {},
"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,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_links": {
"type": "object"
},
"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
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report is been deprecated (i.e. import was skipped)",
"example": false
},
"uploaded_by": {
"type": "object",
"description": "Reference to business partner who uploaded sales report",
"nullable": true
},
"uploaded_at": {
"type": "integer",
"description": "Timestamp when sales report was uploaded",
"example": 1445437680
},
"verified": {
"type": "boolean",
"description": "Indicated whether report was verfied."
},
"verified_at": {
"type": "integer",
"description": "Unix time stamp when sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verfied sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is been processed at the moment",
"example": false
},
"properties": {
"type": "object",
"description": "Additional properties related to the report",
"example": {}
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id",
"_links",
"name",
"screenname"
]
},
"sha1": {
"type": "string",
"description": "SHA1 hash of the file",
"example": "dfb107aec15dd73f0ce8392e1c7989c6723fc861"
},
"type": {
"type": "string",
"description": "Type of the sales report",
"example": "sales_report"
}
},
"required": [
"_id",
"_links",
"error",
"file_name",
"file_size",
"href",
"labels",
"mime_type",
"module",
"processed",
"deprecated",
"uploaded_by",
"uploaded_at",
"verified",
"verified_at",
"verified_by",
"in_progress",
"properties",
"realm",
"sha1",
"type"
]
}
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."
}
}
}
}
}
}
DELETE /resource/v3/sales_reports/{id}
Delete sales report by ID
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the sales report |
Response 204 No Content
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."
}
}
}
}
}
}
Schemas
Sales Report
| Name | Type |
|---|---|
_id |
string Unique identifier for the sales report
Example: |
_links |
|
deprecated |
boolean Indicates whether the report is been deprecated (i.e. import was skipped) |
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: |
in_progress |
boolean Indicates whether the report is been processed at the moment |
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: |
uploaded_at |
integer Timestamp when sales report was uploaded
Example: |
uploaded_by |
Reference to business partner who uploaded sales report |
verified |
boolean Indicated whether report was verfied. |
verified_at |
integer| null Unix time stamp when sales report was verified.
Example: |
verified_by |
Reference to business partner who verfied sales report. |
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. |
| ROYALTY_ACCOUNTING_SUBJECT_TO_ROYALTIES | Defines whether royalties should be applied. |
| ROYALTY_ACCOUNTING_CHANNEL | Defines which royalty rules should apply. |