Back to top

Trade API v2.0

The Publit Trade API offers the methods and resources necessary to programatically implement a Publishing functionality in the Publit system.

The API is a RESTful based API with methods accessible through HTTP-requests. As a RESTful service it supports the common HTTP verbs, and lists resources defined per URL.

Terminology

  • Account - A Publit account of type Retailer or Publisher

  • Client - A customer or an account

  • Customer - An end consumer

  • Publisher - The publisher that owns the right for the product

  • Retailer - The retailer account that uses the API

  • User - A user of an account that can authenticate against the API

  • Contributor - A person that has contributed to a work, for example an author or translator

  • Manifestation - An edition of a work in a specific type (Book/Ebook/Audiobook) and format. Identified by the Publit manifestation_id or it’s unique ISBN

  • Product - An article that can be sold

  • Work - A literary work that has the characteristics that are common to all it’s manifestations

Authentication

All requests to the API need to be authenticated via basic authentication. The authentication is similar to any other basic authentication but can be used to login to specific accounts if a user has more than one.

The Publit authentication string is made up of three parts and should be compiled as follows: user_name;account_id:password

Note the semicolon between user_name and account_id, this separates the user from the account and is specific for the Publit APIs. If the account_id is omitted the user will automatically be logged in the the first available account the system can find for the user.

Credentials will be received by Publit upon agreement to use the API.

The API can also be accessed through tokens, see the Token resource for more information.

Environments

The API has two different environments:

  • Production - Live environment

  • Sandbox - Test environment for development

The sandbox should be used for testing only. The sandbox environment is re-migrated on a regular basis and any changes (for example test orders) made on it from testing will then be lost, and as such it should be viewed as a non-persistant environment. No communication prior to a re-migration of the sandbox environment will be made.

Time

All timestamps conveyed through the APIs are in UTC.

Custom headers

These custom headers will be returned in every authenticated request to the Publit APIs:

  • Token - Token hash

  • account_id - The authenticated account_id

  • user_id - The authenticated user_id

  • locale - The active locale of the request

General GET interface

Most GET resources have the same interface for the query string parameters. These parameters allows for filtering the data and loading relations.

If no other parameters are listed in the GET resources the following query string parameters apply.

INDEX

The index method is a basic method that lists all available resources on a specific endpoint.

The index list can be filtered and manipulated using the following parameters:

  • limit (number, optional) - Limit and offset. Usage: limit=offset,limit or limit=limit

  • with (string, optional) - With querystring parameter. Use for loading relations if any. Usage: with=relation. add relations with comma (,) with=relation,other_relation. See under the Response section of each of the resource methods for more information about which relations are available.

  • scope (string, optional) - Scope querystring parameter. Use for filtering through pre defined scopes, if any. Usage: scope=scope_method or scope=method;qualifier

  • has (string, optional) - Has querystring parameter. Allows for filtering through relations. Usage: has=relation(attribute;operator;value);combinator. Has is only applicable for direct relations, it is not possible to use it on sub-relations.

  • attribute (string, optional) - Allows for filtering directly on model attributes. Usage: created_at=2017-01-01%2000:00:00

  • attribute_args (string, optional) - Allows for enhancing filtering on attributes. Set filtering attribute + _args in the querystring. Usage: created_at=2017-01-01%2000:00:00&created_at_args=GREATER_EQUAL

  • auxiliary_attribute (string, optional) - auxiliary_attribute querystring parameter. Use for loading attributes defined by the resource but not part of the model, if any. Usage: auxiliary_attribute=some_pre_defined_attribute

  • order_by (string, optional) - order_by querystring parameter. Use for ordering responses. Usage: order_by=attribute

  • order_dir (string, optional) - Order direction parameter, use together with order_by. Usage: order_dir=<enum[ASC|DESC]> (default is ASC)

Large data sets and pagination

When calling the Index methods consideration must be taken for response times. Loading a data set that is too large will be memory intensive and slow to parse, and can ultimately result in timeout errors from the APIs.

To make the request faster, more consistent and less error-prone make sure to limit the data set and use pagination to iterate through the data. Also remember that loading additional relations to a resource (with) can make the data set grow exponentially, which should be considered when evaluating how many items to recover in each request.

Any limited data set will return pagination data nodes which can be parsed and used for subsequent calls.

Publit recommends by practice to limit the response using the limit query parameter and page results if needed, and enforces a maximum limit of 500 items per request on each index method call if not stated otherwise.

Example

Query for loading a maximum 20 (limit) products that has been created after 2017-01-01 00:00:00 (created_at and created_at_args) together with the related publisher and the related work and its thema categories (with).

GET ../trade/v2.0/products?with=publisher,work.thema_categories&created_at=2017-01-01%2000:00:00&created_at_args=GREATER_EQUAL;AND&limit=20

Query for loading a maximum of 10 campaigns with an offset of 5 (limit=5,10), scoped by ongoing (scope=ongoing) together with its campaign products (with=campaign_products). The results are ordered descending by id (order_by=id and order_dir=DESC).

GET ../trade/v2.0/campaigns?scope=ongoing&with=campaign_products&order_by=id&order_dir=DESC&limit=5,10

SHOW

The Show method is a method that shows one specific resource on a specific endpoint. Since it allways lists only one resource no additional filtering can be made. But the returned resource can be modified by loading additional relations. The following query parameters apply for the Show methods:

  • with (string, optional) - With querystring parameter. Use for loading relations if any. Usage: with=relation. add relations with comma (,) with=relation,other_relation

  • auxiliary_attribute (string, optional) - auxiliary_attribute querystring parameter. Use for loading attributes defined by the resource but not part of the model, if any. Usage: auxiliary_attribute=some_pre_defined_attribute

Example

Query for loading an order together with a relation to it’s order_rows.

GET ../trade/v2.0/orders/1?with=order_rows

Token

The Token resource creates an authentication token that can be used for subsequent calls against the API.

Any resource that is accessed via credentials and basic auth will return an authentication token that can be used for subsequent calls.

Using token for authentication

When successfully authenticated a return token attribute will be present in the headers. This can be used instead of the password when making further authentication attempts. This is useful as it permits the password to be omitted when making requests.

When authorising using token the authentication string should be compiled as follows: user_name;account_id (note that the password is omitted). And the token should be sent in the header as an attribute called token.

Every time an authentication request to any resource is made without a token, the token will be reset.

Example Headers:

Basic <base64 encoded string (for example myuser)>
Token <token hash>

Token

Creates authorisation token.

Create token
POST/trade/v2.0/token

Example URI

POST /trade/v2.0/token
Request
HideShow
Headers
Basic: <base64 encoded hash>
Response  200
HideShow

Returned if status is ok.

Headers
Content-Type: application/json
Token: <token hash>
user_id: <user_id>
account_id: <account_id>
Body
{
  "data": "OK"
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  404
HideShow

Returned if the service is down.

Product listing

Products

The Products resource is the main resource for fetching new and updated products from Publit.

The Product resource contains basic information about the product (see the response section of each endpoint for more details) but has several relations which can be loaded into it.

Available relations

The relations available for loading into products (with the with keyword in the query string) are:

  • publisher - The publisher of the product

  • publisher.retailer_publisher_details - Specific retailer-publisher details. (See the Retailer publisher details resource for more information).

  • currency - The currency of the price of the product (all prices are always conveyed in the same currency for a specific retailer)

  • work - The related work of the product. Most of it’s data is already available in the product, but is useful as a “bridge” to other data

  • work.description_works - The description of the literary work (and product)

  • work.thema_categories - The Thema categorisation of the literary work. (see http://www.editeur.org/151/thema for more information)

  • language - The language of the product

  • product_work_contributors - The contributors of the literary work connected to the product

  • product_work_contributors.contributor_biography - The biography of the connected contributor

  • product_manifestation_contributors - The contributors of the manifestation connected to the product. These are manifestation-specific contributors, such as readers for audiobook manifestations.

  • product_manifestation_contributors.contributor_biography - The biography of the connected contributor

  • product_measurement - Loads additional measurement data about the product, such as width, height and page amount

  • product_campaigns - List of related product_campaigns, which is a struct containing information about both a campaign (see the campaigns section) and the campaign_product which holds information about a products specific price during a campaign

  • ongoing_product_campaigns - Same as the product_campaigns relation but scoped to only load ongoing campaigns

  • upcoming_product_campaigns - Same as the product_campaigns relation but scoped to only load upcoming campaigns

  • ended_product_campaigns - Same as the product_campaigns relation but scoped to only load ended campaigns

For retailers with special permission to host files the following relation is available on top of the list above:

  • files - The related files of the product

Usage:

?with=<relation>

Available auxiliary attributes

A product can also be loaded with the auxiliary attribute thumbnails. If used the thumbnails attribute will be loaded displaying a list of thumbnails available for representing the product.

Usage:

?auxiliary=thumbnails

Product ingestion example

This is a basic example on how to ingest products.

Best practice

We recommend that the listing should be filtered with a timestamp from the last time any products from Publit was ingested. This enables you to update the delta only without having to fetch every single product for each ingestion.

It also makes for smaller and quicker responses and thus easier parsing and error handling.

Example

The query in this example lists 50 products (limit=50) that has been created or updated after or equal to a certain timestamp, in this case 2017-08-01 12:00:00 (updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND).

GET .../trade/v2.0/products?updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND&auxiliary=thumbnails&with=publisher,product_work_contributors.contributor_biography,product_work_contributors.contributor_biography,product_manifestation_contributors.contributor_biography,product_measurements,work.thema_categories,work.description_works&limit=50

The above request would list 50 products with related information about:

  • publisher

  • contributors (with biographies)

  • description

  • category

  • measurements

  • thumbnails

If more than 50 products exists that matches the filters, the response’s next attribute could be used for pagination through more result pages.

Index
GET/trade/v2.0/products

Example URI

GET /trade/v2.0/products
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "retailer_id": "1",
      "price": "10.0000",
      "currency_id": "1",
      "business_model_id": "1",
      "active": "True",
      "available_at": "2017-01-01 00:00:00",
      "product_id": "1",
      "publisher_id": "1",
      "manifestation_id": "1",
      "work_id": "1",
      "title": "My title",
      "subtitle": "My subtitle",
      "language_id": "1",
      "isbn": "9781234567891",
      "formatted_isbn": "978",
      "updated_at": "2017-01-01 00:00:00",
      "current_price": "10.0000",
      "publisher": {
        "id": "1",
        "company_name": "Publisher AB",
        "imprint": "Publab",
        "retailer_publisher_identifier": "1",
        "retailer_publisher_identification_format": "R-ID",
        "retailer_publisher_details": {
          "id": "1",
          "retailer_account_id": "1",
          "publisher_account_id": "1",
          "retailer_publisher_identifier": "ABC-123",
          "retailer_publisher_identification_format": "retailerA-ID",
          "publit_handles_export": "True",
          "publisher_name": "Publisher AB",
          "retailer_name": "Retailer AB",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00"
        }
      },
      "currency": {
        "id": "1",
        "name": "Swedish Krona",
        "iso3": "SEK",
        "isonum": "752"
      },
      "work": {
        "id": "1",
        "title": "My title",
        "subtitle": "My subtitle",
        "istc": "Hello, world!",
        "language_id": "1",
        "original_publication_year": "2017-01-01 00:00:00",
        "description_works": [
          {
            "id": "1",
            "description": "Some descriptive text...",
            "updated_at": "2017-01-01 00:00:00",
            "pivot": {
              "connected_id": "1",
              "description_work_id": "1",
              "connected_type": "Work",
              "id": "1"
            }
          }
        ],
        "thema_categories": [
          {
            "id": "1",
            "code": "FBA",
            "description": "Modern & contemporary fiction",
            "parent_code": "FB",
            "pivot": {
              "id": "1",
              "work_id": "1",
              "connected_id": "1",
              "type": "Panthema"
            }
          }
        ]
      },
      "language": {
        "id": "1",
        "iso3": "swe",
        "iso2": "se",
        "native_name": "Svenska",
        "name": "Swedish"
      },
      "product_work_contributors": [
        {
          "contributor_id": "1",
          "name": "August",
          "lastname": "Strindberg",
          "sort_name": "Strindberg",
          "prefix": "Hello, world!",
          "birth_date": "1849-01-28 00:00:00",
          "contributor_biography_id": "1",
          "sort_order": "1",
          "product_id": "1",
          "role": "Author",
          "role_onix_code": "A01",
          "work_id": "1",
          "contributor_biograhpy": {
            "id": "1",
            "biography": "Some biographical text about the contributor...",
            "created_at": "2017-01-01 00:00:00",
            "updated_at": "2017-01-01 00:00:00"
          }
        }
      ],
      "product_manifestation_contributors": [
        {
          "contributor_id": "1",
          "name": "August",
          "lastname": "Strindberg",
          "sort_name": "Strindberg",
          "prefix": "Hello, world!",
          "birth_date": "1849-01-28 00:00:00",
          "contributor_biography_id": "1",
          "sort_order": "1",
          "product_id": "1",
          "role": "Author",
          "role_onix_code": "A01",
          "manifestation_id": "1",
          "contributor_biograhpy": {
            "id": "1",
            "biography": "Some biographical text about the contributor...",
            "created_at": "2017-01-01 00:00:00",
            "updated_at": "2017-01-01 00:00:00"
          }
        }
      ],
      "product_measurement": {
        "product_id": "1",
        "pages": "100",
        "length_unit": "mm",
        "width": "210",
        "height": "297",
        "duration": "3600"
      },
      "product_campaigns": [
        {
          "outlet_reference_id": "1_1",
          "outlet_type": "RetailerAccount",
          "campaign_name": "My summer campaign",
          "start_date": "2017-07-01 00:00:00",
          "end_date": "2017-07-30 23:59:59",
          "price": "10.0000",
          "price_tier_id": "1",
          "currency": "SEK"
        }
      ],
      "ongoing_product_campaigns": [
        {
          "outlet_reference_id": "1_1",
          "outlet_type": "RetailerAccount",
          "campaign_name": "My summer campaign",
          "start_date": "2017-07-01 00:00:00",
          "end_date": "2017-07-30 23:59:59",
          "price": "10.0000",
          "price_tier_id": "1",
          "currency": "SEK"
        }
      ],
      "upcoming_product_campaigns": [
        {
          "outlet_reference_id": "1_1",
          "outlet_type": "RetailerAccount",
          "campaign_name": "My summer campaign",
          "start_date": "2017-07-01 00:00:00",
          "end_date": "2017-07-30 23:59:59",
          "price": "10.0000",
          "price_tier_id": "1",
          "currency": "SEK"
        }
      ],
      "ended_product_campaigns": [
        {
          "outlet_reference_id": "1_1",
          "outlet_type": "RetailerAccount",
          "campaign_name": "My summer campaign",
          "start_date": "2017-07-01 00:00:00",
          "end_date": "2017-07-30 23:59:59",
          "price": "10.0000",
          "price_tier_id": "1",
          "currency": "SEK"
        }
      ],
      "files": [
        {
          "id": "1",
          "type": "Ebook",
          "size": "1234567",
          "extension": "epub",
          "mime_type": "application/epub+zip",
          "checkusm": "<md5 file hash>",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00",
          "pivot": {
            "connected_id": "1",
            "file_id": "1"
          }
        }
      ],
      "thumbnails": [
        {
          "id": "1",
          "type": "Ebook",
          "size": "1234567",
          "extension": "epub",
          "mime_type": "application/epub+zip",
          "checkusm": "<md5 file hash>",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of products"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/products/{retailer_product_id}

Example URI

GET /trade/v2.0/products/1
URI Parameters
HideShow
retailer_product_id
number (required) Example: 1

Id of product resource

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "price": "10.0000",
  "currency_id": "1",
  "business_model_id": "1",
  "active": "True",
  "available_at": "2017-01-01 00:00:00",
  "product_id": "1",
  "publisher_id": "1",
  "manifestation_id": "1",
  "work_id": "1",
  "title": "My title",
  "subtitle": "My subtitle",
  "language_id": "1",
  "isbn": "9781234567891",
  "formatted_isbn": "978",
  "updated_at": "2017-01-01 00:00:00",
  "current_price": "10.0000",
  "publisher": {
    "id": "1",
    "company_name": "Publisher AB",
    "imprint": "Publab",
    "retailer_publisher_identifier": "1",
    "retailer_publisher_identification_format": "R-ID",
    "retailer_publisher_details": {
      "id": "1",
      "retailer_account_id": "1",
      "publisher_account_id": "1",
      "retailer_publisher_identifier": "ABC-123",
      "retailer_publisher_identification_format": "retailerA-ID",
      "publit_handles_export": "True",
      "publisher_name": "Publisher AB",
      "retailer_name": "Retailer AB",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  },
  "currency": {
    "id": "1",
    "name": "Swedish Krona",
    "iso3": "SEK",
    "isonum": "752"
  },
  "work": {
    "id": "1",
    "title": "My title",
    "subtitle": "My subtitle",
    "istc": "Hello, world!",
    "language_id": "1",
    "original_publication_year": "2017-01-01 00:00:00",
    "description_works": [
      {
        "id": "1",
        "description": "Some descriptive text...",
        "updated_at": "2017-01-01 00:00:00",
        "pivot": {
          "connected_id": "1",
          "description_work_id": "1",
          "connected_type": "Work",
          "id": "1"
        }
      }
    ],
    "thema_categories": [
      {
        "id": "1",
        "code": "FBA",
        "description": "Modern & contemporary fiction",
        "parent_code": "FB",
        "pivot": {
          "id": "1",
          "work_id": "1",
          "connected_id": "1",
          "type": "Panthema"
        }
      }
    ]
  },
  "language": {
    "id": "1",
    "iso3": "swe",
    "iso2": "se",
    "native_name": "Svenska",
    "name": "Swedish"
  },
  "product_work_contributors": [
    {
      "contributor_id": "1",
      "name": "August",
      "lastname": "Strindberg",
      "sort_name": "Strindberg",
      "prefix": "Hello, world!",
      "birth_date": "1849-01-28 00:00:00",
      "contributor_biography_id": "1",
      "sort_order": "1",
      "product_id": "1",
      "role": "Author",
      "role_onix_code": "A01",
      "work_id": "1",
      "contributor_biograhpy": {
        "id": "1",
        "biography": "Some biographical text about the contributor...",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00"
      }
    }
  ],
  "product_manifestation_contributors": [
    {
      "contributor_id": "1",
      "name": "August",
      "lastname": "Strindberg",
      "sort_name": "Strindberg",
      "prefix": "Hello, world!",
      "birth_date": "1849-01-28 00:00:00",
      "contributor_biography_id": "1",
      "sort_order": "1",
      "product_id": "1",
      "role": "Author",
      "role_onix_code": "A01",
      "manifestation_id": "1",
      "contributor_biograhpy": {
        "id": "1",
        "biography": "Some biographical text about the contributor...",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00"
      }
    }
  ],
  "product_measurement": {
    "product_id": "1",
    "pages": "100",
    "length_unit": "mm",
    "width": "210",
    "height": "297",
    "duration": "3600"
  },
  "product_campaigns": [
    {
      "outlet_reference_id": "1_1",
      "outlet_type": "RetailerAccount",
      "campaign_name": "My summer campaign",
      "start_date": "2017-07-01 00:00:00",
      "end_date": "2017-07-30 23:59:59",
      "price": "10.0000",
      "price_tier_id": "1",
      "currency": "SEK"
    }
  ],
  "ongoing_product_campaigns": [
    {
      "outlet_reference_id": "1_1",
      "outlet_type": "RetailerAccount",
      "campaign_name": "My summer campaign",
      "start_date": "2017-07-01 00:00:00",
      "end_date": "2017-07-30 23:59:59",
      "price": "10.0000",
      "price_tier_id": "1",
      "currency": "SEK"
    }
  ],
  "upcoming_product_campaigns": [
    {
      "outlet_reference_id": "1_1",
      "outlet_type": "RetailerAccount",
      "campaign_name": "My summer campaign",
      "start_date": "2017-07-01 00:00:00",
      "end_date": "2017-07-30 23:59:59",
      "price": "10.0000",
      "price_tier_id": "1",
      "currency": "SEK"
    }
  ],
  "ended_product_campaigns": [
    {
      "outlet_reference_id": "1_1",
      "outlet_type": "RetailerAccount",
      "campaign_name": "My summer campaign",
      "start_date": "2017-07-01 00:00:00",
      "end_date": "2017-07-30 23:59:59",
      "price": "10.0000",
      "price_tier_id": "1",
      "currency": "SEK"
    }
  ],
  "files": [
    {
      "id": "1",
      "type": "Ebook",
      "size": "1234567",
      "extension": "epub",
      "mime_type": "application/epub+zip",
      "checkusm": "<md5 file hash>",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "pivot": {
        "connected_id": "1",
        "file_id": "1"
      }
    }
  ],
  "thumbnails": [
    {
      "id": "1",
      "type": "Ebook",
      "size": "1234567",
      "extension": "epub",
      "mime_type": "application/epub+zip",
      "checkusm": "<md5 file hash>",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "The retailer id"
    },
    "price": {
      "type": "string",
      "description": "The _normal_ price of the product"
    },
    "currency_id": {
      "type": "string",
      "description": "Proprietary currency id"
    },
    "business_model_id": {
      "type": "string",
      "description": "Proprietary business model id"
    },
    "active": {
      "type": "string",
      "enum": [
        "True",
        "False"
      ],
      "description": "Active flag, indicates if the product is commercially available for sale. If `True` the product is avaiable for purchase"
    },
    "available_at": {
      "type": "string",
      "description": "Available date of product. Indicates the date when the product is made available for sale. Only when this time has passed and the `active` flag is true will the product be available for sale"
    },
    "product_id": {
      "type": "string",
      "description": "Proprietary product id"
    },
    "publisher_id": {
      "type": "string",
      "description": "Proprietary publisher id"
    },
    "manifestation_id": {
      "type": "string",
      "description": "Proprietary manifestation id"
    },
    "work_id": {
      "type": "string",
      "description": "Proprietary work id"
    },
    "title": {
      "type": "string",
      "description": "Title of the literary work"
    },
    "subtitle": {
      "type": "string",
      "description": "Subtitle of the literary work"
    },
    "language_id": {
      "type": "string",
      "description": "Proprietary language id"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of the product"
    },
    "formatted_isbn": {
      "type": "string",
      "description": "12-34567-89-1 (string) - Formatted ISBN of the product"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "current_price": {
      "type": "string",
      "description": "The current price of the product. Best practice is to always use this field for storing price of the product"
    },
    "publisher": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "company_name": {
          "type": "string",
          "description": "Name of the publishing company"
        },
        "imprint": {
          "type": "string",
          "description": "Imprint of the publisher"
        },
        "retailer_publisher_identifier": {
          "type": "string",
          "description": "Retailer publisher identifier, if any"
        },
        "retailer_publisher_identification_format": {
          "type": "string",
          "description": "Retailer publisher identification format, if any"
        },
        "retailer_publisher_details": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id of resource (automatically assigned)"
            },
            "retailer_account_id": {
              "type": "string",
              "description": "Proprietary retailer id"
            },
            "publisher_account_id": {
              "type": "string",
              "description": "Proprietary publisher id"
            },
            "retailer_publisher_identifier": {
              "type": "string",
              "description": "The retailers publisher ID"
            },
            "retailer_publisher_identification_format": {
              "type": "string",
              "description": "The type of identification format"
            },
            "publit_handles_export": {
              "type": "string",
              "enum": [
                "True"
              ],
              "description": "This flag indicates if distribution of the product is handled from Publit. (If _False_ the distribution (including order handling) is supposed to be handled elsewhere)."
            },
            "publisher_name": {
              "type": "string",
              "description": "Name of publisher"
            },
            "retailer_name": {
              "type": "string",
              "description": "Name of retailer"
            },
            "created_at": {
              "type": "string",
              "description": "Resource created date. Set automatically. (UTC)"
            },
            "updated_at": {
              "type": "string",
              "description": "Resource updated date. Set automatically. (UTC)"
            }
          },
          "description": "The related retailer publisher details"
        }
      },
      "description": "The related publisher"
    },
    "currency": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of the currency in english"
        },
        "iso3": {
          "type": "string",
          "description": "ISO-4217 standard format of the currency"
        },
        "isonum": {
          "type": "string",
          "description": "ISO-4217 standard numeric format of the currency"
        }
      },
      "description": "The related currency"
    },
    "work": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "title": {
          "type": "string",
          "description": "Title of the work"
        },
        "subtitle": {
          "type": "string",
          "description": "Subtitle of the work"
        },
        "istc": {
          "type": "string",
          "description": "istc code of work, if any"
        },
        "language_id": {
          "type": "string",
          "description": "proprietary language id of the work"
        },
        "original_publication_year": {
          "type": "string",
          "description": "Original year of publication in timestamp format."
        },
        "description_works": {
          "type": "array",
          "description": "Related descriptions of the work"
        },
        "thema_categories": {
          "type": "array",
          "description": "Related Thema categories of the work"
        }
      },
      "description": "The related work"
    },
    "language": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "iso3": {
          "type": "string",
          "description": "ISO three letter code of the language"
        },
        "iso2": {
          "type": "string",
          "description": "ISO two letter code of the language"
        },
        "native_name": {
          "type": "string",
          "description": "Name of the language in the native tongue"
        },
        "name": {
          "type": "string",
          "description": "Name of the language in english"
        }
      },
      "description": "Related language of the product"
    },
    "product_work_contributors": {
      "type": "array",
      "description": "List of related contributors connected to the work"
    },
    "product_manifestation_contributors": {
      "type": "array",
      "description": "List of related contributors connected to the manifestation"
    },
    "product_measurement": {
      "type": "object",
      "properties": {
        "product_id": {
          "type": "string",
          "description": "Id of the related product"
        },
        "pages": {
          "type": "string",
          "description": "Number of pages (Note for digital free flowing formats this is approximated)"
        },
        "length_unit": {
          "type": "string",
          "description": "Length unit of the the width and height attributes"
        },
        "width": {
          "type": "string",
          "description": "Width of the product (only applicable to physical formats)"
        },
        "height": {
          "type": "string",
          "description": "Height of the product (only applicable to physical formats)"
        },
        "duration": {
          "type": "string",
          "description": "Duration of the product (only applicable to audiobook formats)"
        }
      },
      "description": "Related product measurement"
    },
    "product_campaigns": {
      "type": "array",
      "description": "Related campaigns"
    },
    "ongoing_product_campaigns": {
      "type": "array",
      "description": "Related ongoing campaigns"
    },
    "upcoming_product_campaigns": {
      "type": "array",
      "description": "Related upcoming campaigns"
    },
    "ended_product_campaigns": {
      "type": "array",
      "description": "Related ended campaigns"
    },
    "files": {
      "type": "array",
      "description": "Related files (only available for retailers with special permissions to host files)"
    },
    "thumbnails": {
      "type": "array",
      "description": "Auxiliary thumbnails attribute"
    }
  }
}
Response  404
HideShow

Returned if account retailer product id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Campaigns

Campaigns

The campaigns resource lists campaigns and campaign general campaign information such as name, start_date and end_date.

A campaign starts automatically when the start_date is passed. From that point on the current_price attribute in the products resource will change, for the affected products, to the price set in the campaign. Likewise the campaign automatically ends once the end_date has passed - and the current_price will be updated accordingly.

The campaign does also have an active attribute. This attribute is indicates if a created campaign should be regarded as live - this is not the same as an ongoing campaign which is solely defined by the start- and end-dates. As an example an existing campaign can be inactivated by the publisher if they wish to discontinue a campaign (or remove it) - it should then no longer be regarded as live.

Available relations

A campaign can be loaded with the following relations:

  • campaign_products - The related mapping to specific products. Includes references to productID and campaign prices

Available Scopes

The campaign Index resource can be filtered with the following scopes (load by using the scope query string parameter):

  • ongoing - Lists only currently ongoing campaigns

  • upcoming - Lists only campaigns that are to come

  • ended - Lists campaigns that has ended

Index
GET/trade/v2.0/campaigns

Example URI

GET /trade/v2.0/campaigns
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "name": "My campaign",
      "active": "True",
      "start_date": "2017-09-01 00:00:00",
      "end_date": "2017-09-30 23:59:59",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "campaign_products": [
        {
          "id": "1",
          "campaign_id": "1",
          "product_id": "1",
          "price": "10.0000",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of campaigns"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/campaigns/{campaign_id}

Example URI

GET /trade/v2.0/campaigns/1
URI Parameters
HideShow
campaign_id
number (required) Example: 1

Id of requested campaign resource

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "My campaign",
  "active": "True",
  "start_date": "2017-09-01 00:00:00",
  "end_date": "2017-09-30 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "campaign_products": [
    {
      "id": "1",
      "campaign_id": "1",
      "product_id": "1",
      "price": "10.0000",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of the campaign. As named by the Publisher"
    },
    "active": {
      "type": "string",
      "enum": [
        "True",
        "False"
      ],
      "description": "Active flag, indicates if the Campaign is deactivated/cancelled or not"
    },
    "start_date": {
      "type": "string",
      "description": "Timestamp indicating the start of the campaign"
    },
    "end_date": {
      "type": "string",
      "description": "Timestamp indicating the end of the campaign"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "campaign_products": {
      "type": "array",
      "description": "List of related `campaign_products`"
    }
  }
}
Response  404
HideShow

Returned if campaign id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

File

Retailers that host files on own servers can use these resources to fetch and list available files.

The file resources are only available for retailers that are set up to host their own files. To enable an account to be eligible for hosting of files a special agreement must be signed with Publit.

Files

Available auxiliary attributes

The file resource can be loaded with the following auxiliary attributes (using auxiliary query string parameter):

  • presigned_url - A presigned download URL.

Best practice

Using presigned_url is recommended best practice. The presigned URL makes downloading more stable and does not enforce a timeout, which the download resource do, making it better for downoading larger files.

Downloading examples

Using the download resource (via curl)

curl -u "username;account_id:password" -o file.extension https://api.publit.com/trade/v2.0/files/1/download

Using presigned_url (via curl)

curl -o file.extension <presigned_url>

Index
GET/trade/v2.0/files

Example URI

GET /trade/v2.0/files
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "type": "Ebook",
      "size": "1234567",
      "extension": "epub",
      "mime_type": "application/epub+zip",
      "checkusm": "<md5 file hash>",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "presigned_url": "https://some/presigned/url.to.file"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "File list"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/files/{file_id}

Example URI

GET /trade/v2.0/files/1234
URI Parameters
HideShow
file_id
number (required) Example: 1234

Id of the requested file

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "type": "Ebook",
  "size": "1234567",
  "extension": "epub",
  "mime_type": "application/epub+zip",
  "checkusm": "<md5 file hash>",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "presigned_url": "https://some/presigned/url.to.file"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "type": {
      "type": "string",
      "enum": [
        "Ebook",
        "EbookCover",
        "EbookThumbnail",
        "EbookSmallThumbnail",
        "Audiobook",
        "AudiobookCover",
        "AudiobookThumbnail",
        "AudiobookSmallThumbnail"
      ],
      "description": "Type of file"
    },
    "size": {
      "type": "string",
      "description": "The size of the file in bytes"
    },
    "extension": {
      "type": "string",
      "description": "The file extensions of the fie"
    },
    "mime_type": {
      "type": "string",
      "description": "The mime type of the file"
    },
    "checkusm": {
      "type": "string",
      "description": "The md5 file hash of the file"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "presigned_url": {
      "type": "string",
      "description": "Presigned (pre-authenticated) URL to file for downloading. The URL will be valid to use for 5 minutes after creation"
    }
  }
}
Response  404
HideShow

Returned if file id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Download
GET/trade/v2.0/files/{file_id}/download

Example URI

GET /trade/v2.0/files/1234/download
URI Parameters
HideShow
file_id
number (required) Example: 1234

Id of the requested file

Response  200
HideShow
Body
Returned if the request was succesful together with the binary file. The mime-type will be set to the most appropriate for the file.

Order handling

Orders

The orders resource handles listing and creation of orders.

The orders resource is one of the very few resources where the input parameters for creating an order differs from hte actual order data stored. This is to simplify the order creation process.

This resource is not available for proxy retailers.

Available relations

The order resource can be loaded with the following relations:

  • order_statuses - The statuses of the order

  • order_rows - The order rows the order consist of

  • order_rows.order_row_digital_content_key - Content keys for downloading items purchased that is in digital formats

  • order_rows.order_row_digital_content_key.drm_type - DRM type of the downloadable content

  • invoice - The invoice the order is bound to

  • print_orders - The related print orders (for purchases of printed type books only)

Order references

When creating orders different reference numbers can be added, even though they are not required:

  • client_order_reference

  • intermediator_order_reference

Depending on if a retailer acts as an intermediator or not the different fields has different meaning. An easy rule of thumb is this: If the retailer acts as an intermediator the intermediator_order_reference should be used for sending the retailer order identifier. In all other cases the retailers order identifier should be sent in the client_order_reference field (the client in this case refers to the client of Publit - which is the retailer).

These references helps greately to match orders from one system to Publit, and makes any support issues regarding orders much quicker and easier to handle.

As best practice it is always recommended to add a reference number to the order so it can be tracked between different systems.

Examples for creating orders

These are some exmples no how to create orders through the TradeAPI and what to expect in response.

Note that the response and request data is fictional and the example only aims to give an understanding about the data structures.

Simple Ebook purchase order

Simple purchase of ebook. The response for ebook purchases include the placed order, the related order_rows and the related order_row_digital_content_keys from where it is possible to discern information about how to download the purchased contents. The provided client_id points to the authenticated retailer account placing the order and the item_id points to an Ebook product.

Request:

POST ../trade/v2.0/orders

The request could also be sent to: POST ../trade/v2.0/order_preview

Payload data structure
{
  "client_id":1,
  "client_type":"RetailerAccount", 
  "client_order_reference":"ref:12345", 
  "items":[
    {
      //Assuming that the id 1 points to an Ebook
      "item_id":1, 
      "amount":"1", 
      "item_type":"Product"
    } 
  ]
}
Response
[
  {
    "contractor_id": "1",
    "client_type": "RetailerAccount", 
    "client_id": "1", 
    "territory_class_id": "30", 
    "client_order_reference": "ref:12345", 
    "intermediator_id": null, 
    "intermediator_order_reference": null, 
    "delivery_message": null,
    "order_currency_id": "131", 
    "status": "Accepted",
    "invoice_id": "1",
    "updated_at": "2017-10-14 15:46:03", 
    "created_at": "2017-10-14 15:46:03", 
    "id": "1",
    "order_rows": [
      {
        "order_row_type_id": "2",
        "item_id": "1",
        "amount": "1", 
        "price_per_unit_ex_vat": "100.000000", 
        "vat_per_unit": "25.000000", 
        "total_inc_vat": "125.000000", 
        "vat_rate": "0.2500",
        "currency_id": "131",
        "order_row_description": "The Book title : subtitle : 978xxxxxxxxxx",
        "raw_unit_price": "100.000000", 
        "publisher_retailer_discount": "0.00", 
        "order_row_message": null,
        "order_id": "1",
        "updated_at": "2017-10-14 15:46:03", 
        "created_at": "2017-10-14 15:46:03", 
        "id": "1",
        "item_type": "Product",
        "order_row_digital_content_key": 
        { 
          "id": "1",
          "order_row_id": "1", 
          "drm_type_id": "1", 
          "download_key": "6593648b3e697bb9b6785bf3c3efa05535a592c1", 
          "purchase_type": "Purchase",
          "created_at": "2017-10-14 15:46:03",
          "updated_at": "2017-10-14 15:46:03" 
        }
      } 
    ],
    "order_statuses": [ 
      {
        "message": "Order created", 
        "status": "Accepted",
        "order_id": "1",
        "updated_at": "2017-10-14 15:46:03", 
        "created_at": "2017-10-14 15:46:03",
        "id": "1" 
      }
    ] 
  }
]

Multiple Ebook purchase as Intermediator

When placing an intermediary order, where the end consumer will be stated as the purchaser, the end consumer (or customer) can be sent in the payload as a separate object. When using this functionality the client_id points to the customer in Publit (and not the retailer), therefore it is best practice to omit the client_id for this kind of orders and instead only provide the client-object. The intermediator_account_id is obligatory when placing an intermediary type order and the intermediator_account_id points to the account making the actual purchase.

Request:

POST ../trade/v2.0/orders

The request could also be sent to: POST ../trade/v2.0/order_preview

Payload data structure
{
  "client_type":"Customer", 
  "intermediator_account_id":1, // This is the retailer account id (the authenticated account)
  "client_order_reference":"customerref:1234", 
  "intermediator_order_reference":"ref:1234",
  "client":{
    "email":"anders@test.com", 
    "name":"Anders", 
    "lastname":"Andersson", 
    "country_id":216
  }, 
  "items":[
    {
      "item_isbn":"978xxxxxxxxx1", 
      "amount":"1", 
      "item_type":"Product"
    },
    {
      "item_isbn":"978xxxxxxxxx2", 
      "amount":"1", 
      "item_type":"Product"
    }
  ]
}
Response
[
  {
    "contractor_id": "1",
    "client_type": "Customer",
    "client_id": "1",
    "client_order_reference": "customerref:1234", 
    "intermediator_id": "1", 
    "intermediator_order_reference": "ref:1234", 
    "delivery_message": null, 
    "order_currency_id": "131",
    "status": "Accepted",
    "invoice_id": "1",
    "updated_at": "2017-10-15 09:05:58", 
    "created_at": "2017-10-15 09:05:58", 
    "id": "1",
    "order_rows": [
      {
        "order_row_type_id": "2",
        "item_id": "1",
        "amount": "1",
        "price_per_unit_ex_vat": "100.000000", "vat_per_unit": "25.000000",
        "total_inc_vat": "125.000000",
        "vat_rate": "0.2500",
        "currency_id": "131",
        "order_row_description": "The Book title : Sbutitle : 978xxxxxxxxx1",
        "raw_unit_price": "100.000000",
        "publisher_retailer_discount": "0.00", 
        "order_row_message": null,
        "order_id": "1",
        "updated_at": "2017-10-15 09:05:59", 
        "created_at": "2017-10-15 09:05:59", 
        "id": "1",
        "item_type": "Product", 
        "order_row_digital_content_key": {
          "id": "1", 
          "order_row_id": "1", 
          "drm_type_id": "1", 
          "download_key": "e0258a8141e536ffdde056901ac2af614715e109", 
          "purchase_type": "Purchase"
        }
      },
      {
        "order_row_type_id": "2",
        "item_id": "2",
        "amount": "1", 
        "price_per_unit_ex_vat": "108.000000", 
        "vat_per_unit": "27.000000", 
        "total_inc_vat": "135.000000", 
        "vat_rate": "0.2500",
        "currency_id": "131",
        "order_row_description": "The Book title 2 : Subtitle : 978xxxxxxxxx2",
        "raw_unit_price": "108.000000", 
        "publisher_retailer_discount": "0.00", 
        "order_row_message": null,
        "order_id": "1",
        "updated_at": "2017-10-15 09:05:59", 
        "created_at": "2017-10-15 09:05:59",
        "id": "2",
        "item_type": "Product", 
        "order_row_digital_content_key": {
          "id": "2", 
          "order_row_id": "2", 
          "drm_type_id": "1", 
          "download_key": "546ed78f9b0d269715dcc523ce9ca974e11830ea", 
          "purchase_type": "Purchase",
          "created_at": "2017-10-15 09:05:59",
          "updated_at": "2017-10-15 09:05:59" 
        }
      }
    ],
    "order_statuses": [ 
        {
          "message": "Order created", 
          "status": "Accepted",
          "order_id": "1",
          "updated_at": "2017-10-15 09:05:59", 
          "created_at": "2017-10-15 09:05:59", 
          "id": "1"
        }
      ]
  }
]

Index
GET/trade/v2.0/orders

Example URI

GET /trade/v2.0/orders
Response  200
HideShow

Returned if request was successful.

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "data": [
    {
      "id": "1",
      "contractor_id": "1",
      "invoice_id": "1",
      "client_id": "1",
      "client_type": "RetailerAccount",
      "client_order_reference": "abc123",
      "intermediator_id": "1",
      "intermediator_order_reference": "123abc",
      "delivery_message": "Some message",
      "order_currency_id": "1",
      "status": "Accepted",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "order_statuses": [
        {
          "id": "1",
          "order_id": "1",
          "status": "Accepted",
          "message": "order created",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00"
        }
      ],
      "order_rows": [
        {
          "id": "1",
          "order_id": "1",
          "order_row_type_id": "1",
          "item_id": "1",
          "amount": "2",
          "order_row_description": "My Book : My subtitle : 9781234567891",
          "price_per_unit_ex_vat": "100.0000",
          "vat_per_unit": "25.0000",
          "total_inc_vat": "250.0000",
          "vat_rate": "0.2500",
          "currency_id": "1",
          "publisher_retailer_discount": "0.00",
          "raw_unit_price": "100.0000",
          "order_row_message": "null",
          "format": "Epub",
          "item_type": "Product",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00",
          "order_row_digital_content_key": {
            "id": "1",
            "order_row_id": "1",
            "drm_type_id": "1",
            "download_key": "<hash>",
            "purchase_type": "Purchase",
            "created_at": "2017-01-01 00:00:00",
            "updated_at": "2017-01-01 00:00:00",
            "drm_type": {
              "id": "1",
              "name": "Social"
            }
          }
        }
      ],
      "invoice": {
        "id": "1",
        "contractor_id": "1",
        "client_id": "1",
        "client_type": "RetailerAccount",
        "invoice_date": "2017-08-31 23:59:59",
        "pay_date": "2017-09-20 00:00:00",
        "total_inc_vat": "250.0000",
        "total_inc_vat_printable": "250.0000",
        "rounding": "0",
        "currency_id": "1",
        "payment_provider_id": "1",
        "invoice_email_address": "some@mail.com",
        "invoice_address_firstname": "Anders",
        "invoice_address_lastname": "Andersson",
        "invoice_address_street": "Street 1",
        "invoice_address_city": "City",
        "invoice_address_zip": "123 45",
        "invoice_address_country_id": "216",
        "message": "some message",
        "is_addable": "True",
        "invoice_status": "Accepted",
        "invoice_download_key": "<hash>",
        "invoice_number": "123455",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "data": {
      "type": "array",
      "description": "List of orders"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if retailer type is proxy.

Headers
Content-Type: text/html; charset=UTF-8
Body
Forbidden.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/orders/{order_id}

Example URI

GET /trade/v2.0/orders/1234
URI Parameters
HideShow
order_id
number (required) Example: 1234

Id of the requested order

Response  200
HideShow

Returned if request was successful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "contractor_id": "1",
  "invoice_id": "1",
  "client_id": "1",
  "client_type": "RetailerAccount",
  "client_order_reference": "abc123",
  "intermediator_id": "1",
  "intermediator_order_reference": "123abc",
  "delivery_message": "Some message",
  "order_currency_id": "1",
  "status": "Accepted",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "order_statuses": [
    {
      "id": "1",
      "order_id": "1",
      "status": "Accepted",
      "message": "order created",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ],
  "order_rows": [
    {
      "id": "1",
      "order_id": "1",
      "order_row_type_id": "1",
      "item_id": "1",
      "amount": "2",
      "order_row_description": "My Book : My subtitle : 9781234567891",
      "price_per_unit_ex_vat": "100.0000",
      "vat_per_unit": "25.0000",
      "total_inc_vat": "250.0000",
      "vat_rate": "0.2500",
      "currency_id": "1",
      "publisher_retailer_discount": "0.00",
      "raw_unit_price": "100.0000",
      "order_row_message": "null",
      "format": "Epub",
      "item_type": "Product",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "order_row_digital_content_key": {
        "id": "1",
        "order_row_id": "1",
        "drm_type_id": "1",
        "download_key": "<hash>",
        "purchase_type": "Purchase",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00",
        "drm_type": {
          "id": "1",
          "name": "Social"
        }
      }
    }
  ],
  "invoice": {
    "id": "1",
    "contractor_id": "1",
    "client_id": "1",
    "client_type": "RetailerAccount",
    "invoice_date": "2017-08-31 23:59:59",
    "pay_date": "2017-09-20 00:00:00",
    "total_inc_vat": "250.0000",
    "total_inc_vat_printable": "250.0000",
    "rounding": "0",
    "currency_id": "1",
    "payment_provider_id": "1",
    "invoice_email_address": "some@mail.com",
    "invoice_address_firstname": "Anders",
    "invoice_address_lastname": "Andersson",
    "invoice_address_street": "Street 1",
    "invoice_address_city": "City",
    "invoice_address_zip": "123 45",
    "invoice_address_country_id": "216",
    "message": "some message",
    "is_addable": "True",
    "invoice_status": "Accepted",
    "invoice_download_key": "<hash>",
    "invoice_number": "123455",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "contractor_id": {
      "type": "string",
      "description": "The contractor id"
    },
    "invoice_id": {
      "type": "string",
      "description": "The invoice id"
    },
    "client_id": {
      "type": "string",
      "description": "The id of the client (defined by the `client_type`)"
    },
    "client_type": {
      "type": "string",
      "enum": [
        "RetailerAccount",
        "Customer"
      ],
      "description": "The type of client"
    },
    "client_order_reference": {
      "type": "string",
      "description": "The clients order reference"
    },
    "intermediator_id": {
      "type": "string",
      "description": "The id of the intermediator"
    },
    "intermediator_order_reference": {
      "type": "string",
      "description": "The intermediator order reference"
    },
    "delivery_message": {
      "type": "string",
      "description": "A delivery message that should be written on the parcel on delivery of physical books"
    },
    "order_currency_id": {
      "type": "string",
      "description": "Currency of the order"
    },
    "status": {
      "type": "string",
      "enum": [
        "Accepted",
        "Pending",
        "Cancelled"
      ],
      "description": "Status of the order"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "order_statuses": {
      "type": "array",
      "description": "List of order statuses (Note: this does not convey print order statuses such as `Sent`)"
    },
    "order_rows": {
      "type": "array",
      "description": "List of related order rows"
    },
    "invoice": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "contractor_id": {
          "type": "string",
          "description": "The contractor id"
        },
        "client_id": {
          "type": "string",
          "description": "The client id (client is defined by client type)"
        },
        "client_type": {
          "type": "string",
          "enum": [
            "RetailerAccount"
          ],
          "description": "The client type"
        },
        "invoice_date": {
          "type": "string",
          "description": "The invoice timestamp"
        },
        "pay_date": {
          "type": "string",
          "description": "Invoice due timestamp"
        },
        "total_inc_vat": {
          "type": "string",
          "description": "The invoice total (Note: the invoice may be available before it has been sent, but the invoice totals will be recalculated when sent to assure the correct sums)"
        },
        "total_inc_vat_printable": {
          "type": "string",
          "description": "Rounded total"
        },
        "rounding": {
          "type": "string",
          "description": "The rounding of the invoice total"
        },
        "currency_id": {
          "type": "string",
          "description": "Proprietary currency id of the invoice"
        },
        "payment_provider_id": {
          "type": "string",
          "description": "Proprietary payment provider id"
        },
        "invoice_email_address": {
          "type": "string",
          "description": "The email to where the invoice is sent"
        },
        "invoice_address_firstname": {
          "type": "string",
          "description": "Firstname of recipient"
        },
        "invoice_address_lastname": {
          "type": "string",
          "description": "Lastname of recipient"
        },
        "invoice_address_street": {
          "type": "string",
          "description": "Invoice address street"
        },
        "invoice_address_city": {
          "type": "string",
          "description": "Invoice address city"
        },
        "invoice_address_zip": {
          "type": "string",
          "description": "Invoice address zip code"
        },
        "invoice_address_country_id": {
          "type": "string",
          "description": "Invoice address country id (proprietary country id)"
        },
        "message": {
          "type": "string",
          "description": "Invoice message"
        },
        "is_addable": {
          "type": "string",
          "enum": [
            "True",
            "False"
          ],
          "description": "Indicates if invoice can be open for aggregating multiple orders"
        },
        "invoice_status": {
          "type": "string",
          "enum": [
            "Accepted",
            "Cancelled",
            "Pending",
            "Error"
          ],
          "description": "Status of the invoice"
        },
        "invoice_download_key": {
          "type": "string",
          "description": "Download key of invoice. Use to download invoice"
        },
        "invoice_number": {
          "type": "string",
          "description": "The invoice number of the invoice (Note: the invoice number will be bound to the invoice once the invoice date has passed and is null otherwise)"
        },
        "created_at": {
          "type": "string",
          "description": "Resource created date. Set automatically. (UTC)"
        },
        "updated_at": {
          "type": "string",
          "description": "Resource updated date. Set automatically. (UTC)"
        }
      },
      "description": "Related Invoice"
    }
  }
}
Response  404
HideShow

Returned if account order id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if retailer type is proxy.

Headers
Content-Type: text/html; charset=UTF-8
Body
Forbidden.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Store
POST/trade/v2.0/orders

Example URI

POST /trade/v2.0/orders
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "client_type": "RetailerAccount",
  "client_id": 1,
  "intermediator_account_id": 1,
  "client_order_reference": "abc123",
  "intermediator_order_reference": "123abc",
  "order_delivery_phone_number": "123456",
  "delivery_address": {
    "firstname": "Anders",
    "lastname": "Andersson",
    "street": "Street 1",
    "city": "City",
    "zip": "123 45",
    "country_id": "1",
    "company_name": "My company"
  },
  "client": {
    "name": "Anders",
    "lastname": "Andersson",
    "email": "customer@mail.com",
    "country_id": 1,
    "customer_address": {
      "firstname": "Anders",
      "lastname": "Andersson",
      "street": "Street 1",
      "city": "City",
      "zip": "123 45",
      "country_id": "1",
      "company_name": "My company"
    }
  },
  "items": [
    {
      "item_id": 1,
      "item_isbn": "9781234567891",
      "item_type": "Product",
      "amount": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_type": {
      "type": "string",
      "enum": [
        "RetailerAccount",
        "Customer"
      ],
      "description": "The client type of the order"
    },
    "client_id": {
      "type": "number",
      "description": "Id of the client performing the purchase. Either proprietary customer_id (if type is Customer) or proprietary account_id (if type is RetailerAccount). Required if type is RetailerAccount andif type is Customer but the customer is not sent through the customer struct."
    },
    "intermediator_account_id": {
      "type": "number",
      "description": "Intermediator account id (Publit retailer id), required if client_type is set to Customer"
    },
    "client_order_reference": {
      "type": "string",
      "description": "Client order reference"
    },
    "intermediator_order_reference": {
      "type": "string",
      "description": "Intermediator order reference"
    },
    "order_delivery_phone_number": {
      "type": "string",
      "description": "Phone number for delivery messaging (applicable for printed books)"
    },
    "delivery_address": {
      "type": "object",
      "properties": {
        "firstname": {
          "type": "string",
          "description": "First name of recipient"
        },
        "lastname": {
          "type": "string",
          "description": "Last name of recipient"
        },
        "street": {
          "type": "string",
          "description": "Street address of recipient"
        },
        "city": {
          "type": "string",
          "description": "City address of recipient"
        },
        "zip": {
          "type": "string",
          "description": "Delivery address zip code"
        },
        "country_id": {
          "type": "string",
          "description": "Proprietary country id"
        },
        "company_name": {
          "type": "string",
          "description": "Company name of recipient"
        }
      },
      "required": [
        "firstname",
        "street",
        "city",
        "zip",
        "country_id"
      ],
      "description": "Delivery address, if different from the accounts (applicable for printed books)"
    },
    "client": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of customer"
        },
        "lastname": {
          "type": "string",
          "description": "Last name of customer"
        },
        "email": {
          "type": "string",
          "description": "Customer email address"
        },
        "country_id": {
          "type": "number",
          "description": "Proprietary country id of customer"
        },
        "customer_address": {
          "type": "object",
          "properties": {
            "firstname": {
              "type": "string",
              "description": "First name of recipient"
            },
            "lastname": {
              "type": "string",
              "description": "Last name of recipient"
            },
            "street": {
              "type": "string",
              "description": "Street address of recipient"
            },
            "city": {
              "type": "string",
              "description": "City address of recipient"
            },
            "zip": {
              "type": "string",
              "description": "Delivery address zip code"
            },
            "country_id": {
              "type": "string",
              "description": "Proprietary country id"
            },
            "company_name": {
              "type": "string",
              "description": "Company name of recipient"
            }
          },
          "required": [
            "firstname",
            "street",
            "city",
            "zip",
            "country_id"
          ],
          "description": "Delivery address of customer"
        }
      },
      "required": [
        "name",
        "email",
        "country_id",
        "customer_address"
      ],
      "description": "Customer struct data"
    },
    "items": {
      "type": "array",
      "description": "Items to order"
    }
  },
  "required": [
    "client_type",
    "client_id"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "1",
    "contractor_id": "1",
    "invoice_id": "1",
    "client_id": "1",
    "client_type": "RetailerAccount",
    "client_order_reference": "abc123",
    "intermediator_id": "1",
    "intermediator_order_reference": "123abc",
    "delivery_message": "Some message",
    "order_currency_id": "1",
    "status": "Accepted",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00",
    "order_statuses": [
      {
        "id": "1",
        "order_id": "1",
        "status": "Accepted",
        "message": "order created",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00"
      }
    ],
    "order_rows": [
      {
        "id": "1",
        "order_id": "1",
        "order_row_type_id": "1",
        "item_id": "1",
        "amount": "2",
        "order_row_description": "My Book : My subtitle : 9781234567891",
        "price_per_unit_ex_vat": "100.0000",
        "vat_per_unit": "25.0000",
        "total_inc_vat": "250.0000",
        "vat_rate": "0.2500",
        "currency_id": "1",
        "publisher_retailer_discount": "0.00",
        "raw_unit_price": "100.0000",
        "order_row_message": "null",
        "format": "Epub",
        "item_type": "Product",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00",
        "order_row_digital_content_key": {
          "id": "1",
          "order_row_id": "1",
          "drm_type_id": "1",
          "download_key": "<hash>",
          "purchase_type": "Purchase",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00",
          "drm_type": {
            "id": "1",
            "name": "Social"
          }
        }
      }
    ],
    "invoice": {
      "id": "1",
      "contractor_id": "1",
      "client_id": "1",
      "client_type": "RetailerAccount",
      "invoice_date": "2017-08-31 23:59:59",
      "pay_date": "2017-09-20 00:00:00",
      "total_inc_vat": "250.0000",
      "total_inc_vat_printable": "250.0000",
      "rounding": "0",
      "currency_id": "1",
      "payment_provider_id": "1",
      "invoice_email_address": "some@mail.com",
      "invoice_address_firstname": "Anders",
      "invoice_address_lastname": "Andersson",
      "invoice_address_street": "Street 1",
      "invoice_address_city": "City",
      "invoice_address_zip": "123 45",
      "invoice_address_country_id": "216",
      "message": "some message",
      "is_addable": "True",
      "invoice_status": "Accepted",
      "invoice_download_key": "<hash>",
      "invoice_number": "123455",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if retailer type is proxy.

Headers
Content-Type: text/html; charset=UTF-8
Body
Forbidden.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Order Preview

The order preview is a helper method to post an order request to the Publit without actually creating it.

This can be used to ascertain the total cost of the order and available payment providers before attempting to place it.

The resource uses the same data structures as the Orders resource, and the same calculation path but does not actually create the order.

Order Preview
POST/trade/v2.0/order_preview

Example URI

POST /trade/v2.0/order_preview
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "client_type": "RetailerAccount",
  "client_id": 1,
  "intermediator_account_id": 1,
  "client_order_reference": "abc123",
  "intermediator_order_reference": "123abc",
  "order_delivery_phone_number": "123456",
  "delivery_address": {
    "firstname": "Anders",
    "lastname": "Andersson",
    "street": "Street 1",
    "city": "City",
    "zip": "123 45",
    "country_id": "1",
    "company_name": "My company"
  },
  "client": {
    "name": "Anders",
    "lastname": "Andersson",
    "email": "customer@mail.com",
    "country_id": 1,
    "customer_address": {
      "firstname": "Anders",
      "lastname": "Andersson",
      "street": "Street 1",
      "city": "City",
      "zip": "123 45",
      "country_id": "1",
      "company_name": "My company"
    }
  },
  "items": [
    {
      "item_id": 1,
      "item_isbn": "9781234567891",
      "item_type": "Product",
      "amount": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client_type": {
      "type": "string",
      "enum": [
        "RetailerAccount",
        "Customer"
      ],
      "description": "The client type of the order"
    },
    "client_id": {
      "type": "number",
      "description": "Id of the client performing the purchase. Either proprietary customer_id (if type is Customer) or proprietary account_id (if type is RetailerAccount). Required if type is RetailerAccount andif type is Customer but the customer is not sent through the customer struct."
    },
    "intermediator_account_id": {
      "type": "number",
      "description": "Intermediator account id (Publit retailer id), required if client_type is set to Customer"
    },
    "client_order_reference": {
      "type": "string",
      "description": "Client order reference"
    },
    "intermediator_order_reference": {
      "type": "string",
      "description": "Intermediator order reference"
    },
    "order_delivery_phone_number": {
      "type": "string",
      "description": "Phone number for delivery messaging (applicable for printed books)"
    },
    "delivery_address": {
      "type": "object",
      "properties": {
        "firstname": {
          "type": "string",
          "description": "First name of recipient"
        },
        "lastname": {
          "type": "string",
          "description": "Last name of recipient"
        },
        "street": {
          "type": "string",
          "description": "Street address of recipient"
        },
        "city": {
          "type": "string",
          "description": "City address of recipient"
        },
        "zip": {
          "type": "string",
          "description": "Delivery address zip code"
        },
        "country_id": {
          "type": "string",
          "description": "Proprietary country id"
        },
        "company_name": {
          "type": "string",
          "description": "Company name of recipient"
        }
      },
      "required": [
        "firstname",
        "street",
        "city",
        "zip",
        "country_id"
      ],
      "description": "Delivery address, if different from the accounts (applicable for printed books)"
    },
    "client": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of customer"
        },
        "lastname": {
          "type": "string",
          "description": "Last name of customer"
        },
        "email": {
          "type": "string",
          "description": "Customer email address"
        },
        "country_id": {
          "type": "number",
          "description": "Proprietary country id of customer"
        },
        "customer_address": {
          "type": "object",
          "properties": {
            "firstname": {
              "type": "string",
              "description": "First name of recipient"
            },
            "lastname": {
              "type": "string",
              "description": "Last name of recipient"
            },
            "street": {
              "type": "string",
              "description": "Street address of recipient"
            },
            "city": {
              "type": "string",
              "description": "City address of recipient"
            },
            "zip": {
              "type": "string",
              "description": "Delivery address zip code"
            },
            "country_id": {
              "type": "string",
              "description": "Proprietary country id"
            },
            "company_name": {
              "type": "string",
              "description": "Company name of recipient"
            }
          },
          "required": [
            "firstname",
            "street",
            "city",
            "zip",
            "country_id"
          ],
          "description": "Delivery address of customer"
        }
      },
      "required": [
        "name",
        "email",
        "country_id",
        "customer_address"
      ],
      "description": "Customer struct data"
    },
    "items": {
      "type": "array",
      "description": "Items to order"
    }
  },
  "required": [
    "client_type",
    "client_id"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "1",
    "contractor_id": "1",
    "invoice_id": "1",
    "client_id": "1",
    "client_type": "RetailerAccount",
    "client_order_reference": "abc123",
    "intermediator_id": "1",
    "intermediator_order_reference": "123abc",
    "delivery_message": "Some message",
    "order_currency_id": "1",
    "status": "Accepted",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00",
    "order_statuses": [
      {
        "id": "1",
        "order_id": "1",
        "status": "Accepted",
        "message": "order created",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00"
      }
    ],
    "order_rows": [
      {
        "id": "1",
        "order_id": "1",
        "order_row_type_id": "1",
        "item_id": "1",
        "amount": "2",
        "order_row_description": "My Book : My subtitle : 9781234567891",
        "price_per_unit_ex_vat": "100.0000",
        "vat_per_unit": "25.0000",
        "total_inc_vat": "250.0000",
        "vat_rate": "0.2500",
        "currency_id": "1",
        "publisher_retailer_discount": "0.00",
        "raw_unit_price": "100.0000",
        "order_row_message": "null",
        "format": "Epub",
        "item_type": "Product",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00",
        "order_row_digital_content_key": {
          "id": "1",
          "order_row_id": "1",
          "drm_type_id": "1",
          "download_key": "<hash>",
          "purchase_type": "Purchase",
          "created_at": "2017-01-01 00:00:00",
          "updated_at": "2017-01-01 00:00:00",
          "drm_type": {
            "id": "1",
            "name": "Social"
          }
        }
      }
    ],
    "invoice": {
      "id": "1",
      "contractor_id": "1",
      "client_id": "1",
      "client_type": "RetailerAccount",
      "invoice_date": "2017-08-31 23:59:59",
      "pay_date": "2017-09-20 00:00:00",
      "total_inc_vat": "250.0000",
      "total_inc_vat_printable": "250.0000",
      "rounding": "0",
      "currency_id": "1",
      "payment_provider_id": "1",
      "invoice_email_address": "some@mail.com",
      "invoice_address_firstname": "Anders",
      "invoice_address_lastname": "Andersson",
      "invoice_address_street": "Street 1",
      "invoice_address_city": "City",
      "invoice_address_zip": "123 45",
      "invoice_address_country_id": "216",
      "message": "some message",
      "is_addable": "True",
      "invoice_status": "Accepted",
      "invoice_download_key": "<hash>",
      "invoice_number": "123455",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if retailer type is proxy.

Headers
Content-Type: text/html; charset=UTF-8
Body
Forbidden.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Order download

The order download resource downloads any digital format books purchased.

Example

Example for downloading an epub file through CURL:

$ curl -u "username;account_id:password" -o file.epub https://api.publit.com/v2.0/order/{order_id}/download/{download_key}

Download
GET/v2.0/order/{order_id}/download/{download_key}

Example URI

GET /v2.0/order/1234/download/
URI Parameters
HideShow
order_id
number (required) Example: 1234

Id of the order the pruchased book belongs to

download_key
number (required) Example: <download hash>

The download key (hash as received from the order_row_digital_content_key object - see the Orders resource)

Response  200
HideShow
Body
Returned if request was succesful, together with a file. The mime-type depends on the file that is downloaded.
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Sales And Settlements

The Sales and Settlements resources are resources intended for reporting consumption (Sales) and for reporting Settlements (actual revenue value that will be paid). These resources are only available for retailers that don’t perform transactions directly in Publit via the Orders resource.

Sales

The sales resource can be used to list and report sales/consumption of books fetched from Publit.

A sales row consists of a product, the total revenue the product has brought in and the total quantity sold during the sales period defined by start_date and end_date. The sales resource is viewed as an aggregated sales list for a certain period of a time.

As this is merely for consumption reporting purposes the revenue can be omitted if it can not be calculated at the time of reporting. The quantity can be reported as a float, meaning that partial consumptions of books can also be reported (eg: 0.5 means half of a consumption).

A sales row is unique for the time period and ISBN.

Index
GET/trade/v2.0/sales

Example URI

GET /trade/v2.0/sales
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "retailer_id": "1",
      "currency": "SEK",
      "product_id": "1",
      "business_model_id": "1",
      "isbn": "9781234567890",
      "amount": "1.5",
      "revenue": "200.00",
      "start_date": "2017-01-01 00:00:00",
      "end_date": "2017-03-31 23:59:59",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of sales"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/sales/{sales_id}

Example URI

GET /trade/v2.0/sales/1
URI Parameters
HideShow
sales_id
number (required) Example: 1

Id of the requested sales row

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "currency": "SEK",
  "product_id": "1",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2017-01-01 00:00:00",
  "end_date": "2017-03-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "product_id": {
      "type": "string",
      "description": "Id of product sold"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  404
HideShow

Returned if sales_id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Store
POST/trade/v2.0/sales

Example URI

POST /trade/v2.0/sales
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "currency": "SEK",
  "product_id": "1",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2017-01-01 00:00:00",
  "end_date": "2017-03-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "product_id": {
      "type": "string",
      "description": "Id of product sold"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
[
  {
    "id": "1",
    "retailer_id": "1",
    "currency": "SEK",
    "product_id": "1",
    "business_model_id": "1",
    "isbn": "9781234567890",
    "amount": "1.5",
    "revenue": "200.00",
    "start_date": "2017-01-01 00:00:00",
    "end_date": "2017-03-31 23:59:59",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  409
HideShow

Returned if a sales row for the specific ISBN and time period already exists

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Settlements

The settlements resource can be used to report aggregated settlement data for a certain period.

The reported rows will be used by Publit as basis for invoicing the Retailer.

A settlements row consists of a product (via ISBN), the total revenue the product has brought in and the total quantity sold during the sales period defined by start_date and end_date. The quantity can be reported as a float, meaning that partial consumptions of books can also be reported (eg: 0.5 means half of a consumption).

A settlements row can also have the attributes retailer_reference and retailer_row_reference. These attributes can be used to match rows in the Publit system to the retailer system. The retailer_reference is the reference Publit will use when sending the invoice - this is basically a means to match a Publit invoice to the retailers own payment reference. The retailer_row_reference is a unique reference that can be set per reported row. This can be used by the Retailer to match certain reported settlement rows in the Publit system to their own system.

Immutability

A settlement row can only be altered during a specified time period after it has been sent (the period will be agreed upon by the Retailer and Publit). After which it will be “locked” and immutable. The time period is intended for double checking that the reported settlements are correct before Publit can invoice the Retailer.

In order to be able to create an invoice Publit will lock the settlements data shortly before invoicing. Any faults in the data that is found after this can be adjusted in the next reporting period.

Index
GET/trade/v2.0/settlements

Example URI

GET /trade/v2.0/settlements
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "retailer_id": "1",
      "retailer_reference": "abc",
      "retailer_row_reference": "bcd",
      "currency": "SEK",
      "business_model_id": "1",
      "isbn": "9781234567890",
      "amount": "1.5",
      "revenue": "200.00",
      "start_date": "2016-12-01 00:00:00",
      "end_date": "2016-12-31 23:59:59",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of settlements"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/settlements/{settlement_id}

Example URI

GET /trade/v2.0/settlements/1
URI Parameters
HideShow
settlement_id
number (required) Example: 1

Id of the requested settlement row

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "retailer_reference": "abc",
  "retailer_row_reference": "bcd",
  "currency": "SEK",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2016-12-01 00:00:00",
  "end_date": "2016-12-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "retailer_reference": {
      "type": "string",
      "description": "123 (string) - Retailer settlement reference"
    },
    "retailer_row_reference": {
      "type": "string",
      "description": "234 (string) - Retailer settlement row reference"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  404
HideShow

Returned if settlement_id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Store
POST/trade/v2.0/settlements

Example URI

POST /trade/v2.0/settlements
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "retailer_reference": "abc",
  "retailer_row_reference": "bcd",
  "currency": "SEK",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2016-12-01 00:00:00",
  "end_date": "2016-12-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "retailer_reference": {
      "type": "string",
      "description": "123 (string) - Retailer settlement reference"
    },
    "retailer_row_reference": {
      "type": "string",
      "description": "234 (string) - Retailer settlement row reference"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
[
  {
    "id": "1",
    "retailer_id": "1",
    "retailer_reference": "abc",
    "retailer_row_reference": "bcd",
    "currency": "SEK",
    "business_model_id": "1",
    "isbn": "9781234567890",
    "amount": "1.5",
    "revenue": "200.00",
    "start_date": "2016-12-01 00:00:00",
    "end_date": "2016-12-31 23:59:59",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Update
PUT/trade/v2.0/settlements/{settlement_id}

Example URI

PUT /trade/v2.0/settlements/1
URI Parameters
HideShow
settlement_id
number (required) Example: 1

Id of the requested settlement row

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "retailer_reference": "abc",
  "retailer_row_reference": "bcd",
  "currency": "SEK",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2016-12-01 00:00:00",
  "end_date": "2016-12-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "retailer_reference": {
      "type": "string",
      "description": "123 (string) - Retailer settlement reference"
    },
    "retailer_row_reference": {
      "type": "string",
      "description": "234 (string) - Retailer settlement row reference"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
[
  {
    "id": "1",
    "retailer_id": "1",
    "retailer_reference": "abc",
    "retailer_row_reference": "bcd",
    "currency": "SEK",
    "business_model_id": "1",
    "isbn": "9781234567890",
    "amount": "1.5",
    "revenue": "200.00",
    "start_date": "2016-12-01 00:00:00",
    "end_date": "2016-12-31 23:59:59",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if the settlements row has become immutable.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  404
HideShow

Returned if settlement_id is not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Delete
DELETE/trade/v2.0/settlements/{settlement_id}

Example URI

DELETE /trade/v2.0/settlements/1
URI Parameters
HideShow
settlement_id
number (required) Example: 1

Id of the settlement row to delete

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_id": "1",
  "retailer_reference": "abc",
  "retailer_row_reference": "bcd",
  "currency": "SEK",
  "business_model_id": "1",
  "isbn": "9781234567890",
  "amount": "1.5",
  "revenue": "200.00",
  "start_date": "2016-12-01 00:00:00",
  "end_date": "2016-12-31 23:59:59",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_id": {
      "type": "string",
      "description": "Retailer account id"
    },
    "retailer_reference": {
      "type": "string",
      "description": "123 (string) - Retailer settlement reference"
    },
    "retailer_row_reference": {
      "type": "string",
      "description": "234 (string) - Retailer settlement row reference"
    },
    "currency": {
      "type": "string",
      "description": "ISO code of currency used for sale"
    },
    "business_model_id": {
      "type": "string",
      "description": "Id of business model"
    },
    "isbn": {
      "type": "string",
      "description": "ISBN of product sold"
    },
    "amount": {
      "type": "string",
      "description": "Quantity of sold products (for indicated time period). Can be a float number"
    },
    "revenue": {
      "type": "string",
      "description": "Revenue of sold products (whole revenue of row)"
    },
    "start_date": {
      "type": "string",
      "description": "Start date (timestamp) of reported sales period"
    },
    "end_date": {
      "type": "string",
      "description": "End date (tmestamp) of reported sales period"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  },
  "required": [
    "currency",
    "isbn",
    "amount",
    "revenue",
    "start_date",
    "end_date"
  ]
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  403
HideShow

Returned if the settlements row has become immutable.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  404
HideShow

Returned if settlement_id is not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Accounts

Accounts

The accounts resource allows for managing the Retailer accounts that the user is connected to.

Index
GET/trade/v2.0/accounts

Example URI

GET /trade/v2.0/accounts
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "name": "Retailer account name",
      "type": "Retailer",
      "account_number": "12345",
      "contractor_id": "1",
      "country_id": "216",
      "language_id": "430",
      "organisation_type": "Company",
      "company_name": "My company AB",
      "contact_person_firstname": "Anders",
      "contact_person_lastname": "Andersson",
      "organisation_number": "123456-7890",
      "vat_reg_number": "SE1234567890",
      "primary_email": "email@company.com",
      "invoice_email": "economy@company.com",
      "phone": "12-34567890",
      "alternate_phone": "23-45678901",
      "profile_image_id": "null",
      "active": "True",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "deleted_at": "NULL",
      "language": {
        "id": "1",
        "iso3": "swe",
        "iso2": "se",
        "native_name": "Svenska",
        "name": "Swedish"
      },
      "country": {
        "id": "1",
        "name": "Sweden",
        "native_name": "Sverige",
        "language_id": "1",
        "iso2": "SE",
        "iso3": "SWE",
        "isonum": "752",
        "currency_id": "131"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of accounts"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/accounts/{account_id}

Example URI

GET /trade/v2.0/accounts/1
URI Parameters
HideShow
account_id
number (required) Example: 1

Id of the requested account

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "Retailer account name",
  "type": "Retailer",
  "account_number": "12345",
  "contractor_id": "1",
  "country_id": "216",
  "language_id": "430",
  "organisation_type": "Company",
  "company_name": "My company AB",
  "contact_person_firstname": "Anders",
  "contact_person_lastname": "Andersson",
  "organisation_number": "123456-7890",
  "vat_reg_number": "SE1234567890",
  "primary_email": "email@company.com",
  "invoice_email": "economy@company.com",
  "phone": "12-34567890",
  "alternate_phone": "23-45678901",
  "profile_image_id": "null",
  "active": "True",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "deleted_at": "NULL",
  "language": {
    "id": "1",
    "iso3": "swe",
    "iso2": "se",
    "native_name": "Svenska",
    "name": "Swedish"
  },
  "country": {
    "id": "1",
    "name": "Sweden",
    "native_name": "Sverige",
    "language_id": "1",
    "iso2": "SE",
    "iso3": "SWE",
    "isonum": "752",
    "currency_id": "131"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of the account"
    },
    "type": {
      "type": "string",
      "enum": [
        "Retailer"
      ],
      "description": "Type of account"
    },
    "account_number": {
      "type": "string",
      "description": "Proprietary account number"
    },
    "contractor_id": {
      "type": "string",
      "description": "Contractor id (the id of the Publit entity connected to the account)"
    },
    "country_id": {
      "type": "string",
      "description": "Proprietary country id"
    },
    "language_id": {
      "type": "string",
      "description": "Proprietary language id"
    },
    "organisation_type": {
      "type": "string",
      "enum": [
        "Company",
        "Private"
      ],
      "description": "Organisation type"
    },
    "company_name": {
      "type": "string",
      "description": "Company name"
    },
    "contact_person_firstname": {
      "type": "string",
      "description": "Contact person"
    },
    "contact_person_lastname": {
      "type": "string",
      "description": "Contact person"
    },
    "organisation_number": {
      "type": "string",
      "description": "Organisation number"
    },
    "vat_reg_number": {
      "type": "string",
      "description": "VAT registration number"
    },
    "primary_email": {
      "type": "string",
      "description": "Primary contact email address"
    },
    "invoice_email": {
      "type": "string",
      "description": "Invoice email address"
    },
    "phone": {
      "type": "string",
      "description": "Contact phone number"
    },
    "alternate_phone": {
      "type": "string",
      "description": "Alternative contact phone number"
    },
    "profile_image_id": {
      "type": "string",
      "description": "Profile image"
    },
    "active": {
      "type": "string",
      "enum": [
        "True"
      ],
      "description": "Indicates if the retailer account is active for ordering"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "deleted_at": {
      "type": "string",
      "description": "Resource deleted date. Set automatically. (UTC)"
    },
    "language": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "iso3": {
          "type": "string",
          "description": "ISO three letter code of the language"
        },
        "iso2": {
          "type": "string",
          "description": "ISO two letter code of the language"
        },
        "native_name": {
          "type": "string",
          "description": "Name of the language in the native tongue"
        },
        "name": {
          "type": "string",
          "description": "Name of the language in english"
        }
      },
      "description": "Related language"
    },
    "country": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of country"
        },
        "native_name": {
          "type": "string",
          "description": "Name of country in the native language of the country"
        },
        "language_id": {
          "type": "string",
          "description": "Proprietary language id of the related language spoken in the country"
        },
        "iso2": {
          "type": "string",
          "description": "iso2 (ISO-3166) code of the country"
        },
        "iso3": {
          "type": "string",
          "description": "iso3 (ISO-3166) code of the country"
        },
        "isonum": {
          "type": "string",
          "description": "numeric iso (ISO-3166) code of the country"
        },
        "currency_id": {
          "type": "string",
          "description": "proprietary currency id connected to the country"
        }
      },
      "description": "Related country"
    }
  }
}
Response  404
HideShow

Returned if account order id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Update
PUT/trade/v2.0/accounts/{account_id}

Example URI

PUT /trade/v2.0/accounts/1
URI Parameters
HideShow
account_id
number (required) Example: 1

Id of the account to update

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "Retailer account name",
  "type": "Retailer",
  "account_number": "12345",
  "contractor_id": "1",
  "country_id": "216",
  "language_id": "430",
  "organisation_type": "Company",
  "company_name": "My company AB",
  "contact_person_firstname": "Anders",
  "contact_person_lastname": "Andersson",
  "organisation_number": "123456-7890",
  "vat_reg_number": "SE1234567890",
  "primary_email": "email@company.com",
  "invoice_email": "economy@company.com",
  "phone": "12-34567890",
  "alternate_phone": "23-45678901",
  "profile_image_id": "null",
  "active": "True",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "deleted_at": "NULL",
  "language": {
    "id": "1",
    "iso3": "swe",
    "iso2": "se",
    "native_name": "Svenska",
    "name": "Swedish"
  },
  "country": {
    "id": "1",
    "name": "Sweden",
    "native_name": "Sverige",
    "language_id": "1",
    "iso2": "SE",
    "iso3": "SWE",
    "isonum": "752",
    "currency_id": "131"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of the account"
    },
    "type": {
      "type": "string",
      "enum": [
        "Retailer"
      ],
      "description": "Type of account"
    },
    "account_number": {
      "type": "string",
      "description": "Proprietary account number"
    },
    "contractor_id": {
      "type": "string",
      "description": "Contractor id (the id of the Publit entity connected to the account)"
    },
    "country_id": {
      "type": "string",
      "description": "Proprietary country id"
    },
    "language_id": {
      "type": "string",
      "description": "Proprietary language id"
    },
    "organisation_type": {
      "type": "string",
      "enum": [
        "Company",
        "Private"
      ],
      "description": "Organisation type"
    },
    "company_name": {
      "type": "string",
      "description": "Company name"
    },
    "contact_person_firstname": {
      "type": "string",
      "description": "Contact person"
    },
    "contact_person_lastname": {
      "type": "string",
      "description": "Contact person"
    },
    "organisation_number": {
      "type": "string",
      "description": "Organisation number"
    },
    "vat_reg_number": {
      "type": "string",
      "description": "VAT registration number"
    },
    "primary_email": {
      "type": "string",
      "description": "Primary contact email address"
    },
    "invoice_email": {
      "type": "string",
      "description": "Invoice email address"
    },
    "phone": {
      "type": "string",
      "description": "Contact phone number"
    },
    "alternate_phone": {
      "type": "string",
      "description": "Alternative contact phone number"
    },
    "profile_image_id": {
      "type": "string",
      "description": "Profile image"
    },
    "active": {
      "type": "string",
      "enum": [
        "True"
      ],
      "description": "Indicates if the retailer account is active for ordering"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "deleted_at": {
      "type": "string",
      "description": "Resource deleted date. Set automatically. (UTC)"
    },
    "language": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "iso3": {
          "type": "string",
          "description": "ISO three letter code of the language"
        },
        "iso2": {
          "type": "string",
          "description": "ISO two letter code of the language"
        },
        "native_name": {
          "type": "string",
          "description": "Name of the language in the native tongue"
        },
        "name": {
          "type": "string",
          "description": "Name of the language in english"
        }
      },
      "description": "Related language"
    },
    "country": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of country"
        },
        "native_name": {
          "type": "string",
          "description": "Name of country in the native language of the country"
        },
        "language_id": {
          "type": "string",
          "description": "Proprietary language id of the related language spoken in the country"
        },
        "iso2": {
          "type": "string",
          "description": "iso2 (ISO-3166) code of the country"
        },
        "iso3": {
          "type": "string",
          "description": "iso3 (ISO-3166) code of the country"
        },
        "isonum": {
          "type": "string",
          "description": "numeric iso (ISO-3166) code of the country"
        },
        "currency_id": {
          "type": "string",
          "description": "proprietary currency id connected to the country"
        }
      },
      "description": "Related country"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "Retailer account name",
  "type": "Retailer",
  "account_number": "12345",
  "contractor_id": "1",
  "country_id": "216",
  "language_id": "430",
  "organisation_type": "Company",
  "company_name": "My company AB",
  "contact_person_firstname": "Anders",
  "contact_person_lastname": "Andersson",
  "organisation_number": "123456-7890",
  "vat_reg_number": "SE1234567890",
  "primary_email": "email@company.com",
  "invoice_email": "economy@company.com",
  "phone": "12-34567890",
  "alternate_phone": "23-45678901",
  "profile_image_id": "null",
  "active": "True",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "deleted_at": "NULL",
  "language": {
    "id": "1",
    "iso3": "swe",
    "iso2": "se",
    "native_name": "Svenska",
    "name": "Swedish"
  },
  "country": {
    "id": "1",
    "name": "Sweden",
    "native_name": "Sverige",
    "language_id": "1",
    "iso2": "SE",
    "iso3": "SWE",
    "isonum": "752",
    "currency_id": "131"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of the account"
    },
    "type": {
      "type": "string",
      "enum": [
        "Retailer"
      ],
      "description": "Type of account"
    },
    "account_number": {
      "type": "string",
      "description": "Proprietary account number"
    },
    "contractor_id": {
      "type": "string",
      "description": "Contractor id (the id of the Publit entity connected to the account)"
    },
    "country_id": {
      "type": "string",
      "description": "Proprietary country id"
    },
    "language_id": {
      "type": "string",
      "description": "Proprietary language id"
    },
    "organisation_type": {
      "type": "string",
      "enum": [
        "Company",
        "Private"
      ],
      "description": "Organisation type"
    },
    "company_name": {
      "type": "string",
      "description": "Company name"
    },
    "contact_person_firstname": {
      "type": "string",
      "description": "Contact person"
    },
    "contact_person_lastname": {
      "type": "string",
      "description": "Contact person"
    },
    "organisation_number": {
      "type": "string",
      "description": "Organisation number"
    },
    "vat_reg_number": {
      "type": "string",
      "description": "VAT registration number"
    },
    "primary_email": {
      "type": "string",
      "description": "Primary contact email address"
    },
    "invoice_email": {
      "type": "string",
      "description": "Invoice email address"
    },
    "phone": {
      "type": "string",
      "description": "Contact phone number"
    },
    "alternate_phone": {
      "type": "string",
      "description": "Alternative contact phone number"
    },
    "profile_image_id": {
      "type": "string",
      "description": "Profile image"
    },
    "active": {
      "type": "string",
      "enum": [
        "True"
      ],
      "description": "Indicates if the retailer account is active for ordering"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "deleted_at": {
      "type": "string",
      "description": "Resource deleted date. Set automatically. (UTC)"
    },
    "language": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "iso3": {
          "type": "string",
          "description": "ISO three letter code of the language"
        },
        "iso2": {
          "type": "string",
          "description": "ISO two letter code of the language"
        },
        "native_name": {
          "type": "string",
          "description": "Name of the language in the native tongue"
        },
        "name": {
          "type": "string",
          "description": "Name of the language in english"
        }
      },
      "description": "Related language"
    },
    "country": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of country"
        },
        "native_name": {
          "type": "string",
          "description": "Name of country in the native language of the country"
        },
        "language_id": {
          "type": "string",
          "description": "Proprietary language id of the related language spoken in the country"
        },
        "iso2": {
          "type": "string",
          "description": "iso2 (ISO-3166) code of the country"
        },
        "iso3": {
          "type": "string",
          "description": "iso3 (ISO-3166) code of the country"
        },
        "isonum": {
          "type": "string",
          "description": "numeric iso (ISO-3166) code of the country"
        },
        "currency_id": {
          "type": "string",
          "description": "proprietary currency id connected to the country"
        }
      },
      "description": "Related country"
    }
  }
}
Response  400
HideShow

Returned if request malformed or faulty.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Retailer Publisher Details

The retailer publisher details list retailer specific details about the connected publishers.

If the retailer needs proprietary information about the publishers, such as retailer proprietary IDs, this is where it is stored. If the retailer does not need any proprietary information this resource may be of little interest.

Usually the retailer publisher details is loaded through relations from the products resource during product ingestion. But this resource can be used to fetch details separately. Can be used to check new connected publishers.

Index
GET/trade/v2.0/retailer_publisher_details

Example URI

GET /trade/v2.0/retailer_publisher_details
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "retailer_account_id": "1",
      "publisher_account_id": "1",
      "retailer_publisher_identifier": "ABC-123",
      "retailer_publisher_identification_format": "retailerA-ID",
      "publit_handles_export": "True",
      "publisher_name": "Publisher AB",
      "retailer_name": "Retailer AB",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00",
      "publisher_account": {
        "id": "1",
        "name": "Retailer account name",
        "type": "Retailer",
        "account_number": "12345",
        "contractor_id": "1",
        "country_id": "216",
        "language_id": "430",
        "organisation_type": "Company",
        "company_name": "My company AB",
        "contact_person_firstname": "Anders",
        "contact_person_lastname": "Andersson",
        "organisation_number": "123456-7890",
        "vat_reg_number": "SE1234567890",
        "primary_email": "email@company.com",
        "invoice_email": "economy@company.com",
        "phone": "12-34567890",
        "alternate_phone": "23-45678901",
        "profile_image_id": "null",
        "active": "True",
        "created_at": "2017-01-01 00:00:00",
        "updated_at": "2017-01-01 00:00:00",
        "deleted_at": "NULL"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of retailer publisher details"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/retailer_publisher_details/{retailer_publisher_details_id}

Example URI

GET /trade/v2.0/retailer_publisher_details/1
URI Parameters
HideShow
retailer_publisher_details_id
number (required) Example: 1

Id of the requested retailer publisher detail

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "retailer_account_id": "1",
  "publisher_account_id": "1",
  "retailer_publisher_identifier": "ABC-123",
  "retailer_publisher_identification_format": "retailerA-ID",
  "publit_handles_export": "True",
  "publisher_name": "Publisher AB",
  "retailer_name": "Retailer AB",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00",
  "publisher_account": {
    "id": "1",
    "name": "Retailer account name",
    "type": "Retailer",
    "account_number": "12345",
    "contractor_id": "1",
    "country_id": "216",
    "language_id": "430",
    "organisation_type": "Company",
    "company_name": "My company AB",
    "contact_person_firstname": "Anders",
    "contact_person_lastname": "Andersson",
    "organisation_number": "123456-7890",
    "vat_reg_number": "SE1234567890",
    "primary_email": "email@company.com",
    "invoice_email": "economy@company.com",
    "phone": "12-34567890",
    "alternate_phone": "23-45678901",
    "profile_image_id": "null",
    "active": "True",
    "created_at": "2017-01-01 00:00:00",
    "updated_at": "2017-01-01 00:00:00",
    "deleted_at": "NULL"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "retailer_account_id": {
      "type": "string",
      "description": "Proprietary retailer id"
    },
    "publisher_account_id": {
      "type": "string",
      "description": "Proprietary publisher id"
    },
    "retailer_publisher_identifier": {
      "type": "string",
      "description": "The retailers publisher ID"
    },
    "retailer_publisher_identification_format": {
      "type": "string",
      "description": "The type of identification format"
    },
    "publit_handles_export": {
      "type": "string",
      "enum": [
        "True"
      ],
      "description": "This flag indicates if distribution of the product is handled from Publit. (If _False_ the distribution (including order handling) is supposed to be handled elsewhere)."
    },
    "publisher_name": {
      "type": "string",
      "description": "Name of publisher"
    },
    "retailer_name": {
      "type": "string",
      "description": "Name of retailer"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    },
    "publisher_account": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of the account"
        },
        "type": {
          "type": "string",
          "enum": [
            "Retailer"
          ],
          "description": "Type of account"
        },
        "account_number": {
          "type": "string",
          "description": "Proprietary account number"
        },
        "contractor_id": {
          "type": "string",
          "description": "Contractor id (the id of the Publit entity connected to the account)"
        },
        "country_id": {
          "type": "string",
          "description": "Proprietary country id"
        },
        "language_id": {
          "type": "string",
          "description": "Proprietary language id"
        },
        "organisation_type": {
          "type": "string",
          "enum": [
            "Company",
            "Private"
          ],
          "description": "Organisation type"
        },
        "company_name": {
          "type": "string",
          "description": "Company name"
        },
        "contact_person_firstname": {
          "type": "string",
          "description": "Contact person"
        },
        "contact_person_lastname": {
          "type": "string",
          "description": "Contact person"
        },
        "organisation_number": {
          "type": "string",
          "description": "Organisation number"
        },
        "vat_reg_number": {
          "type": "string",
          "description": "VAT registration number"
        },
        "primary_email": {
          "type": "string",
          "description": "Primary contact email address"
        },
        "invoice_email": {
          "type": "string",
          "description": "Invoice email address"
        },
        "phone": {
          "type": "string",
          "description": "Contact phone number"
        },
        "alternate_phone": {
          "type": "string",
          "description": "Alternative contact phone number"
        },
        "profile_image_id": {
          "type": "string",
          "description": "Profile image"
        },
        "active": {
          "type": "string",
          "enum": [
            "True"
          ],
          "description": "Indicates if the retailer account is active for ordering"
        },
        "created_at": {
          "type": "string",
          "description": "Resource created date. Set automatically. (UTC)"
        },
        "updated_at": {
          "type": "string",
          "description": "Resource updated date. Set automatically. (UTC)"
        },
        "deleted_at": {
          "type": "string",
          "description": "Resource deleted date. Set automatically. (UTC)"
        }
      },
      "description": "Related publisher account"
    }
  }
}
Response  404
HideShow

Returned if account order id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Static resources

These resources serves as read-only helpers to understand and lookup data from the Publit Trade API.

Countries

The countries resource shows information about countries mapped by Publit proprietary ids.

Index
GET/trade/v2.0/countries

Example URI

GET /trade/v2.0/countries
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "name": "Sweden",
      "native_name": "Sverige",
      "language_id": "1",
      "iso2": "SE",
      "iso3": "SWE",
      "isonum": "752",
      "currency_id": "131",
      "language": {
        "id": "1",
        "iso3": "swe",
        "iso2": "se",
        "native_name": "Svenska",
        "name": "Swedish"
      },
      "currency": {
        "id": "1",
        "name": "Swedish Krona",
        "iso3": "SEK",
        "isonum": "752"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/countries/{country_id}

Example URI

GET /trade/v2.0/countries/1
URI Parameters
HideShow
country_id
number (required) Example: 1

Id of the requested country

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "Sweden",
  "native_name": "Sverige",
  "language_id": "1",
  "iso2": "SE",
  "iso3": "SWE",
  "isonum": "752",
  "currency_id": "131",
  "language": {
    "id": "1",
    "iso3": "swe",
    "iso2": "se",
    "native_name": "Svenska",
    "name": "Swedish"
  },
  "currency": {
    "id": "1",
    "name": "Swedish Krona",
    "iso3": "SEK",
    "isonum": "752"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of country"
    },
    "native_name": {
      "type": "string",
      "description": "Name of country in the native language of the country"
    },
    "language_id": {
      "type": "string",
      "description": "Proprietary language id of the related language spoken in the country"
    },
    "iso2": {
      "type": "string",
      "description": "iso2 (ISO-3166) code of the country"
    },
    "iso3": {
      "type": "string",
      "description": "iso3 (ISO-3166) code of the country"
    },
    "isonum": {
      "type": "string",
      "description": "numeric iso (ISO-3166) code of the country"
    },
    "currency_id": {
      "type": "string",
      "description": "proprietary currency id connected to the country"
    },
    "language": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "iso3": {
          "type": "string",
          "description": "ISO three letter code of the language"
        },
        "iso2": {
          "type": "string",
          "description": "ISO two letter code of the language"
        },
        "native_name": {
          "type": "string",
          "description": "Name of the language in the native tongue"
        },
        "name": {
          "type": "string",
          "description": "Name of the language in english"
        }
      },
      "description": "Related language"
    },
    "currency": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of resource (automatically assigned)"
        },
        "name": {
          "type": "string",
          "description": "Name of the currency in english"
        },
        "iso3": {
          "type": "string",
          "description": "ISO-4217 standard format of the currency"
        },
        "isonum": {
          "type": "string",
          "description": "ISO-4217 standard numeric format of the currency"
        }
      },
      "description": "Related currency"
    }
  }
}
Response  404
HideShow

Returned if country id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Languages

The languages resource shows information about languages mapped by Publit proprietary ids.

Index
GET/trade/v2.0/languages

Example URI

GET /trade/v2.0/languages
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "iso3": "swe",
      "iso2": "se",
      "native_name": "Svenska",
      "name": "Swedish"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of languages"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/languages/{language_id}

Example URI

GET /trade/v2.0/languages/1
URI Parameters
HideShow
language_id
number (required) Example: 1

Id of the requested language

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "iso3": "swe",
  "iso2": "se",
  "native_name": "Svenska",
  "name": "Swedish",
  "countries": [
    {
      "id": "1",
      "name": "Sweden",
      "native_name": "Sverige",
      "language_id": "1",
      "iso2": "SE",
      "iso3": "SWE",
      "isonum": "752",
      "currency_id": "131"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "iso3": {
      "type": "string",
      "description": "ISO three letter code of the language"
    },
    "iso2": {
      "type": "string",
      "description": "ISO two letter code of the language"
    },
    "native_name": {
      "type": "string",
      "description": "Name of the language in the native tongue"
    },
    "name": {
      "type": "string",
      "description": "Name of the language in english"
    },
    "countries": {
      "type": "array",
      "description": "Related countries"
    }
  }
}
Response  404
HideShow

Returned if country id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Currencies

The currencies resource shows information about currencies mapped by Publit proprietary ids.

Index
GET/trade/v2.0/currencies

Example URI

GET /trade/v2.0/currencies
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "name": "Swedish Krona",
      "iso3": "SEK",
      "isonum": "752",
      "countries": [
        {
          "id": "1",
          "name": "Sweden",
          "native_name": "Sverige",
          "language_id": "1",
          "iso2": "SE",
          "iso3": "SWE",
          "isonum": "752",
          "currency_id": "131"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of currencies"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/currencies/{currency_id}

Example URI

GET /trade/v2.0/currencies/1
URI Parameters
HideShow
currency_id
number (required) Example: 1

Id of the requested currency

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "name": "Swedish Krona",
  "iso3": "SEK",
  "isonum": "752",
  "countries": [
    {
      "id": "1",
      "name": "Sweden",
      "native_name": "Sverige",
      "language_id": "1",
      "iso2": "SE",
      "iso3": "SWE",
      "isonum": "752",
      "currency_id": "131"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "name": {
      "type": "string",
      "description": "Name of the currency in english"
    },
    "iso3": {
      "type": "string",
      "description": "ISO-4217 standard format of the currency"
    },
    "isonum": {
      "type": "string",
      "description": "ISO-4217 standard numeric format of the currency"
    },
    "countries": {
      "type": "array",
      "description": "List of related countries"
    }
  }
}
Response  404
HideShow

Returned if country id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Categories

The categories resource shows category information.

Thema

The Thema-category list shows the available Thema categories (as defined by http://www.editeur.org/151/thema) supported in the Publit system.

Index
GET/trade/v2.0/categories/thema/trade/v2.0/categories/thema{?=query string parameters

Example URI

GET /trade/v2.0/categories/thema/trade/v2.0/categories/thema{?=query string parameters
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "code": "FBA",
      "description": "Modern & contemporary fiction",
      "parent_code": "FB"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of Thema categories"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/categories/thema/{thema_category_id}

Example URI

GET /trade/v2.0/categories/thema/1
URI Parameters
HideShow
thema_category_id
number (required) Example: 1

Id of the requested Thema category code

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "code": "FBA",
  "description": "Modern & contemporary fiction",
  "parent_code": "FB"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "code": {
      "type": "string",
      "description": "Thema category code"
    },
    "description": {
      "type": "string",
      "description": "Description of the category"
    },
    "parent_code": {
      "type": "string",
      "description": "The parent code"
    }
  }
}
Response  404
HideShow

Returned if thema category id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Category Convert

The convert resource allows for converting a category from one type to another. Currently Publit supports conversion from Thema to Bic and vice versa.

Convert
GET/trade/v2.0/categories/convert/from/{category_type}/{code_list}

Example URI

GET /trade/v2.0/categories/convert/from/thema/F,FA
URI Parameters
HideShow
category_type
enum (required) Example: thema

Type of code to convert from.

  • thema

  • bic

code_list
string (required) Example: F,FA

Codes of type defined by category_type to convert from. Separated by comma.

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "data": [
    {
      "bic_code": "A",
      "thema_code": "A",
      "description": "The Arts"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "data": {
      "type": "array",
      "description": "list of converted codes"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Contributor Roles

The contributor roles resource lists information about the available contributor roles supported by Publit.

Index
GET/trade/v2.0/contributor_roles

Example URI

GET /trade/v2.0/contributor_roles
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "count": "1",
  "next": "../resource{?query}&limit=x,y",
  "prev": "../resource{?query}&limit=x,y",
  "data": [
    {
      "id": "1",
      "role": "Author",
      "onix_code": "A01",
      "description": "Author of textual work.",
      "use_as_primary": "True",
      "created_at": "2017-01-01 00:00:00",
      "updated_at": "2017-01-01 00:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "string",
      "description": "Count of resources returned"
    },
    "next": {
      "type": "string",
      "description": "URL to next page of results"
    },
    "prev": {
      "type": "string",
      "description": "URL to previous page of results"
    },
    "data": {
      "type": "array",
      "description": "List of contributor roles"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Show
GET/trade/v2.0/contributor_roles/{contributor_role_id}

Example URI

GET /trade/v2.0/contributor_roles/1
URI Parameters
HideShow
contributor_role_id
number (required) Example: 1

Id of the requested contributor role

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "id": "1",
  "role": "Author",
  "onix_code": "A01",
  "description": "Author of textual work.",
  "use_as_primary": "True",
  "created_at": "2017-01-01 00:00:00",
  "updated_at": "2017-01-01 00:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of resource (automatically assigned)"
    },
    "role": {
      "type": "string",
      "description": "Role name"
    },
    "onix_code": {
      "type": "string",
      "description": "Role ONIX code"
    },
    "description": {
      "type": "string",
      "description": "Description of role"
    },
    "use_as_primary": {
      "type": "string",
      "enum": [
        "True"
      ],
      "description": "Flag to indicate if the role can be used as primary contribution to a work"
    },
    "created_at": {
      "type": "string",
      "description": "Resource created date. Set automatically. (UTC)"
    },
    "updated_at": {
      "type": "string",
      "description": "Resource updated date. Set automatically. (UTC)"
    }
  }
}
Response  404
HideShow

Returned if contributor role id was not found.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Aggregate resources

Most of the resources in the API can be aggregated by using the different aggregate resource.

The aggregate resource allows for running an aggregate method of a set of results for different resources.

The following aggregate methods exist:

  • Count

  • Sum

  • Max

  • Min

  • Avg

Examples

Each resource to aggregate also accepts the same filters as can be used by the resource directly allowing for advanced use of aggregations.

Following examples uses count as aggregation method.

Example for counting countries that uses a specific language Request: GET ../v2.0/count/countries?language_id=130

Response:

{
    "count": 49
}

Example for counting countries and grouping it by language_id

This is slightly more complex but can be useful as it provides an aggregate for each group of results.

Request: GET ../v2.0/count/countries?group_by=language_id

Response:

{
    "count": [
        {
            "language_id": 9,
            "count": 2
        },
        {
            "language_id": 14,
            "count": 1
        },
        ...
    ]
}

Example for counting countries and grouping it by language_id and loading the language relation

This is an even greater extension of the previous example as it does not only count each aggregate of groups but also loads the language relation to each group.

Request: GET ../v2.0/count/countries?group_by=language_id

Response:

{
    "count": [
        {
            "language_id": 19,
            "count": 2,
            "language": {
                "id": 9,
                "iso3": "afr",
                "iso2": "af",
                "native_name": "Afrikaans",
                "name": "Afrikaans"
            }
        },
        {
            "language_id": 14,
            "count": 1,
            "language": {
                "id": 14,
                "iso3": "sqi",
                "iso2": "sq",
                "native_name": "Shqip",
                "name": "Albanian"
            }
        },
        ...
    ]
}

Count

Counts number of resources.

Show
GET/trade/v2.0/count/{resource}

Example URI

GET /trade/v2.0/count/countries
URI Parameters
HideShow
resource
string (required) Example: countries

The resource to count

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "count": 223
}
Response  404
HideShow

Returned if resource was not found or could not be aggregated.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Sum

Sums an aggregate of resources.

Sum takes two parameters (resource and attribute) separated by a semicolon ;.

If the attribute can not be summed the result will be {"sum":0}.

Show
GET/trade/v2.0/sum/{resource_attribute}

Example URI

GET /trade/v2.0/sum/sales;revenue
URI Parameters
HideShow
resource_attribute
string (required) Example: sales;revenue

The resource and attribute to count

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "sum": "10000.00"
}
Response  404
HideShow

Returned if resource was not found or could not be aggregated.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Max

Max retrieves the maximum value of the specified resources attribute.

Max takes two parameters (resource and attribute) separated by a semicolon ;.

Show
GET/trade/v2.0/max/{resource_attribute}

Example URI

GET /trade/v2.0/max/products;price
URI Parameters
HideShow
resource_attribute
string (required) Example: products;price

The resource and attribute

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "max": "150.00"
}
Response  404
HideShow

Returned if resource was not found or could not be aggregated.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Min

Min retrieves the minimum value of the specified resources attribute.

Min takes two parameters (resource and attribute) separated by a semicolon ;.

Show
GET/trade/v2.0/min/{resource_attribute}

Example URI

GET /trade/v2.0/min/products;price
URI Parameters
HideShow
resource_attribute
string (required) Example: products;price

The resource and attribute

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "max": "1.00"
}
Response  404
HideShow

Returned if resource was not found or could not be aggregated.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Avg

Avg retrieves the average value of the specified resources attribute.

Avg takes two parameters (resource and attribute) separated by a semicolon ;.

Show
GET/trade/v2.0/avg/{resource_attribute}

Example URI

GET /trade/v2.0/avg/products;price
URI Parameters
HideShow
resource_attribute
string (required) Example: products;price

The resource and attribute

Response  200
HideShow

Returned if request was succesful

Headers
Content-Type: application/json
Body
{
  "avg": "25.37"
}
Response  404
HideShow

Returned if resource was not found or could not be aggregated.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}
Response  401
HideShow

Returned if unauthorized.

Headers
Content-Type: text/html; charset=UTF-8
Body
Invalid credentials.
Response  500
HideShow

Returned if server had problems.

Headers
Content-Type: application/json
Body
{
  "Code": 1,
  "Type": "Error type",
  "Errors": [
    {
      "Info": "Some specific error information",
      "Type": "Not found"
    }
  ],
  "CombinedInfo": "Some combined error information"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "Code": {
      "type": "number",
      "description": "HTTP response code"
    },
    "Type": {
      "type": "string",
      "description": "Type of error"
    },
    "Errors": {
      "type": "array",
      "description": "Errors explanation"
    },
    "CombinedInfo": {
      "type": "string",
      "description": "Combined error information string"
    }
  }
}

Status check

The status check resource is a light weight resource that needs no authentication and shows information about if the API status is ok.

If any HTTP-status in the 300, 400 or 500 range is returned the server has problems nad can not be reached. Contact Publit for information if this happens.

The status check resource is not scoped to a specific API but available directly under https://api.publit.com/v2.0/status_check.

Status Check

Status Check
GET/v2.0/status_check

Example URI

GET /v2.0/status_check
Response  200
HideShow

Returned if request was succesful.

Headers
Content-Type: application/json
Body
{
  "server_status": "OK"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "server_status": {
      "type": "string",
      "description": "Flag indicating the status of the server"
    }
  }
}

Generated by aglio on 19 Dec 2017