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
Responses
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_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,
"partially_imported": false,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_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": "integer",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_uuid": {
"type": "string",
"description": "UUID identifier for the sales report",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_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
},
"partially_imported": {
"type": "boolean",
"description": "Indicates whether the report was partially imported before an error occurred",
"example": false
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report has 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": "Indicates whether the report was verified."
},
"verified_at": {
"type": "integer",
"description": "Unix timestamp when the sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verified the sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is being 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
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_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"
]
},
"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",
"partially_imported",
"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"
]
}
Responses
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_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,
"partially_imported": false,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_uuid": {
"type": "string",
"description": "UUID identifier for the sales report",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_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
},
"partially_imported": {
"type": "boolean",
"description": "Indicates whether the report was partially imported before an error occurred",
"example": false
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report has 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": "Indicates whether the report was verified."
},
"verified_at": {
"type": "integer",
"description": "Unix timestamp when the sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verified the sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is being 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
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_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"
]
},
"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",
"partially_imported",
"deprecated",
"uploaded_by",
"uploaded_at",
"verified",
"verified_at",
"verified_by",
"in_progress",
"properties",
"realm",
"sha1",
"type"
]
}
{
"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/sales_reports/{id}
Retrieve a single sales report by ID
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | The unique identifier of the sales report |
Responses
{
"_id": "072d54f7-00d6-42ee-96de-0d7689d1ea3b",
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_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,
"partially_imported": false,
"deprecated": false,
"uploaded_by": {},
"uploaded_at": 1445437680,
"verified": true,
"verified_at": 1445437680,
"verified_by": {},
"in_progress": false,
"properties": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"sha1": "dfb107aec15dd73f0ce8392e1c7989c6723fc861",
"type": "sales_report"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the sales report",
"example": "072d54f7-00d6-42ee-96de-0d7689d1ea3b"
},
"_uuid": {
"type": "string",
"description": "UUID identifier for the sales report",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_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
},
"partially_imported": {
"type": "boolean",
"description": "Indicates whether the report was partially imported before an error occurred",
"example": false
},
"deprecated": {
"type": "boolean",
"description": "Indicates whether the report has 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": "Indicates whether the report was verified."
},
"verified_at": {
"type": "integer",
"description": "Unix timestamp when the sales report was verified.",
"nullable": true,
"example": 1445437680
},
"verified_by": {
"type": "object",
"description": "Reference to business partner who verified the sales report.",
"nullable": true
},
"in_progress": {
"type": "boolean",
"description": "Indicates whether the report is being 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
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_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"
]
},
"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",
"partially_imported",
"deprecated",
"uploaded_by",
"uploaded_at",
"verified",
"verified_at",
"verified_by",
"in_progress",
"properties",
"realm",
"sha1",
"type"
]
}
{
"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
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | The unique identifier of the sales report |
Responses
{
"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."
}
}
}
}
}
}
{
"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 | Description | Example |
|---|---|---|---|
_id |
integer |
Unique identifier for the sales report |
072d54f7-00d6-42ee-96de-0d7689d1ea3b |
_links |
object | ||
_uuid |
string |
UUID identifier for the sales report |
333c0d12-f5ef-11f0-8321-00505699575c |
deprecated |
boolean |
Indicates whether the report has been deprecated (i.e. import was skipped) |
false |
error |
string| null |
Any error associated with the report, if applicable |
|
file_name |
string |
The file name of the report |
gxyde-amazon-us-reseller.txt |
file_size |
integer |
The size of the file in bytes |
498098498 |
href |
string |
URL to download the sales report |
https://api.openpublishing.com/rpc/sales_importer_download.... |
in_progress |
boolean |
Indicates whether the report is being processed at the moment |
false |
labels |
Array<string> |
List of labels associated with the report |
[] |
mime_type |
string |
MIME type of the file |
application/octet-stream |
module |
string |
The module from which the sales report was generated |
amazonsalespreview |
partially_imported |
boolean |
Indicates whether the report was partially imported before an error occurred |
false |
processed |
boolean |
Indicates whether the report has been processed |
true |
properties |
object |
Additional properties related to the report |
{} |
realm |
Properties: _id, _uuid, _links, name, screenname |
Reference to realm which owns this object |
|
realm._id |
integer |
Realm ID |
23 |
realm._uuid |
string |
ID of resource in V4 version of resource |
|
realm._links |
object | ||
realm.name |
string |
Name of the realm |
xyzpublishing |
realm.screenname |
string |
Screenname of the realm |
XYZ Publishing |
sha1 |
string |
SHA1 hash of the file |
dfb107aec15dd73f0ce8392e1c7989c6723fc861 |
type |
string |
Type of the sales report |
sales_report |
uploaded_at |
integer |
Timestamp when sales report was uploaded |
1445437680 |
uploaded_by |
object| null |
Reference to business partner who uploaded sales report |
|
verified |
boolean |
Indicates whether the report was verified. |
|
verified_at |
integer| null |
Unix timestamp when the sales report was verified. |
1445437680 |
verified_by |
object| null |
Reference to business partner who verified the 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. |